Wednesday, June 18, 2008

The importance of documentation (and having a place to put it)

As systems administrators, we deal in information. Doing our jobs requires applying skills that we've acquired over the course of our careers, and relating those skills to the systems we come in contact with. In order to do that job correctly, we need to know a great deal of the intricacies of what we're dealing with.

Some of us have small enough networks that keeping everything in mind is tedious but possible. Others have literally hundreds or thousands of servers, and dozens upon dozens of circuits. Most of us are somewhere in-between.

I mentioned it before, in Managing your network contracts, but keeping track of all these details is a task best suited for a computer. There is no sysadmin I've ever seen who wouldn't benefit (or didn't already) from some sort of centralized documentation repository.

Some people choose to write their own. That's certainly a valid choice, if a bit time consuming. At my company, I implemented an internal Wiki, based on MediaWiki. Since wikis are useful for many things, but kludgy for a great many more, I supplement this with an installation of GLPI, which keeps track of all my physical assets, and some logical as well. It's not the simplest software I've used, but it's by far easier than others. 

One of the benefits of the wiki is that it allows others in the organization to document what's important to them, as well. Our operations staff has (virtual) reams of paper documenting processes and information. Our corporate contact list is there, as well as the holiday schedule.  It's a nice, centralized repository of information for a company that isn't large enough to have a full-fledged intranet web. 

The downsides of wikis are that they're primarily edited manually. I have not yet figured how how to reliably import or export information to the database programmatically, other than brute force web-submission. There is also the fact that wikis are (MediaWiki is, anyway, others may not be) anti-hierarchy. The article names are in a flat filespace, so having the same name twice is an issue. It's important to impress this upon everyone creating pages, so that no-one thinks they have page "comments" to themselves. An artificial hierarchy seems to work alright, though, as long as everyone plays along. 

In the end, however, it doesn't matter whether you use a wiki or a notebook in the server room. It's important that your assets, procedures, and information base be documented. Never forget that IT infrastructures have bus factors too.