Start a knowledge base

I work with a relatively small I.T. team. Being half developer and half I.T. administrator, human resources can get quite stretched when it comes to domain knowledge. When one person goes on vacation, their absence is felt.

One of the things we did a couple of years ago to mitigate this is to start a knowledge base. Knowledge bases used to be these huge complicated things that people would have to manage. I still remember the times when I worked for a big consulting firm that had whole teams dedicated to maintaining and producing the knowledge base. But with the advent of "Web 2.0" and the popularity of blogs and WIKIs, this hurdle has been greatly overcome. The focus becomes on the content rather than the presentation. The fact that everyone can contribute to its content makes the content that much more relevant and useful.

Here are some tips to starting a successful knowledge base:

1. Encourage and convince your team (and other stakeholders) that this is a good thing. Resistance can be hard to overcome. It may come in the form of people who have ingrained knowledge of systems and fear losing their jobs. But job replacement is not the goal of a knowledge system. By documenting knowledge, you not only spread the wealth of knowledge, you encourage reproduction of leadership, and you encourage those that have the knowledge to learn more. (Don't they say that the best student is often the teacher?)

2. Identify some areas that desperately need documentation. Keep a running list of topics.

3. Find a repository. In our team, we prefer to use a WIKI. We find the collaborative nature of WIKIs suitable for something that changes constantly like a knowledge base. As we find new problems and new solutions, we update the WIKI. There are many WIKIs out there of varying size - find one that suits the size of your organization, and run with it. For us, we decided to use JSPWiki - mostly because of its simplicity, and the fact that it uses the file system as a repository. This made for simple backups as well as maintenance. Others will want to chose a more robust system such as TWiki or MediaWIKI where the UI is more full featured. Again, the emphasis should be on content, not presentation.

Wikipedia (a wiki in an of itself) has a great comparison page on wiki engines.

3. Have a reasonable organizational structure in mind. I'm cautious about saying this a little bit because sometimes finding the structure can be daunting. If this is the case, do step 4 first. But it is a good idea to have a general idea of a structure you may wish to use. It helps you to seed the Wiki with initial ideas. Then you can refine the structure later.

In our team, we decided to use the OSI layers as an initial structure. Because many of the things we wanted to write about in our knowledge base fell under one of these layers, this was a logical point to start. Other teams may wish to use other forms of organization. Whatever you choose, do try to make sure that it ties into some sort of existing context that your users will understand.

4. Start writing! In our team, many of our initial pages were just simply a description of what that page was intended to be. For instance, we may have a page called "ListOfServerIPs" that just contains the intention for that page. Then, as problems came up, we all made a commitment to find the relevant page and update it. In other words, there is not always a need to do this huge "dump" of initial information - just start using the knowledge base from this point forward, and the background will often fill itself in.

5. Repeat steps 2 through 4. Knowledge bases (like the people who remember the knowledge) are meant to be organic. It is only as good as the last person who maintained it - so, make it an iterative process. As your knowledge base grows, reevaluate if there might be a better way of organizing the information and write/rewrite pages accordingly. Of course, one nice thing about Wikis is that they are also web pages with full hyperlink capabilities so creating new "index" pages can be easy. A lot of WIKIs nowadays also employ tag and search systems allowing for greater flexibility in structure.