Documentation for system administrators
Writing and maintaining documentation is something most system administrators don't like. Experience learns that documentation is seldom kept up-to-date after delivery.
In my opinion, this has two reasons:
- System admins don't see the use of documentation, because they experience very little profit from it;
- Documentation is hard to change (mostly because of procedures) and it is unappreciated work.
It is useful to give both issues enough attention. For system administration documentation it is certainly useful if admins can find relevant information easily.
Searching
In Google one can find an answer on a technical question usually within 30 seconds by stating clever chosen search terms. Searching documentation on a network drive within the company, usually organized in a very deep directory tree, takes much longer to finish. This is very frustrating to the system admins, who prefer to use Google to find answers, even when the answers are available somewhere in the system documentation.
Changing
Changing is not very rewarding. After changing documentation, it is not visible to others easily what changed and who did it. For these reasons much documentation is not updated at all.
Wiki's
Modern technology can solve much of the described problems. Using Wiki's with search capabilities, for instance. The success of wiki's is best seen on http://www.wikipedia.org, where many people voluntarily invest much spare time in updating and creating articles.
People don't have to document articles on Wikipedia, but they want to do it, even for free. The reason is visibility: the whole world can see what you did and if you amend or improve documentation, your name is connected to this forever. Also information ypu created is easily found in Wikipedia.
Murdoc
My open source project Murdoc is a simple, but handy tool for exposing (already existing) documentation via a web interface with search capabilities. It is even possible for computer systems to be documented automatically, so the documentation is always up-to-date.
Murdoc contains a standard directory setup in which system administrators can organize their documentation.
This entry was posted on Friday 22 December 2006