How to maintain network documentation?

Dear Tom/Christine/Strata, I have read The Practice of System and Network Administration. I still use it as a reference and find it very useful when training new employees at [my company].

One big problem I still have is network documentation. We use many tools to document our client networks. Some work OK. Some are very cumbersome to use. It is very hard to get techs to document their work and changes. It's even harder when they have 20 different tools to use and they do not know how/can't remember how to use all of them.

We are currently using Word to keep our documentation in. We start off with a template and fill in the fields. This is OK except the template fields change over time and the older network documentation for clients does not get updated with the new fields. Also, the formatting in Word gets all out of sorts and the techs spend a lot of time trying to get the document formatted properly.

I am looking for a web-based, database driven system for network documentation. Ideally, the system would allow me to create database forms/templates to fill in for standards based documentation and allow me to create free-hand documents like a wiki. Then I would like to organize the pages into a book format and print it off. I would also like to be able to search on it too.

Am I asking for too much? Do you know of such a system?

Sincerely,
Networked in Texas

Dear Networked,

Thanks for writing! We're glad you enjoy the book enough to share it with new employees.

Having so many tools can be very painful to learn. Any reason to not use a tool is going to be employed, especially if people don't feel the pain when documentation gets out of date. The best inventory/documentation systems feed other systems so that the encouragement to get the database right is that nothing works if they don't :-). For example, having the docs feed the monitoring system (or somehow influence if the payroll system works properly :-) ).

I've seen a number of home-grown systems that maintain databases and present web front-ends. I don't think I've seen commercial or free ones. Though, Brent Chapman has been doing interesting things at Netomata http://www.netomata.com/products/ncg I don't think that's what you are looking for. I know that there is network inventory stuff available for maintaining fiber plants around the world, but I don't think that's useful in this situation. Visio has a network diagram mode that can actually do network discovery. Not sure if that helps.

The home-grown system I use right now uses YAML files that get checked into a source code repository. On check-in we run "make" which builds HTML pages that are diagrams of what various racks contain. We also use pre-submit checks to trigger programs that verify the data is consistant. Sadly updating YAML files requires more technical skill than a web front end.

Rather thank MS-Word, have you considered something that stores the data in a structured format so other systems can process the data? Everyone knows how to edit an Excel spreadsheet. It is easy to write scripts that extract the data to be sent to something that draws the diagrams in HTML.

Rather than expect people to learn many tools often it is better to have a single tool for data input (web form, YAML, Excel, Google Spreadsheets, etc.) and let a Makefile or cron job do the rest of the work. That way they only have to learn one tool but all the ancillary tasks still happen.

I work at Google so if you don't mind me plugging one of our products: Google Spreadsheets has three benefits here: (1) the document is stored online, so there is no confusion from emailing spreadsheets around, (2) multiple people can be editing a spreadsheet at the same time, so there is no locking needed, (3) there is an API that lets you manipulate the spreadsheet form Python or other language, therefore you can extract the data from a script you run to do useful things with the data. The API permits updates, so you could write web front ends (or even shell scripts) that add data to it.

Thanks, Tom

P.S. Ok, blog readers! Do you have a tool or suggestion for this reader! Please post to the comments section with your solutions!