Writing Good Network Documentation?

_Hellfire_ asks: "As the Senior Technician at a small mobile computing service I have just recently wrapped up a rather large networking job. The network includes a Linux Primary Domain Controller, Cisco router, port redirection for VNC, tape backup solution etc. - all in all fairly complex and not the sort of thing that someone not already familiar could easily take over. I therefore want to write good, comprehensive documentation for other technicians in case I'm not specifically available. How have other Slashdotters tackled this issue? Where do you start? How do you make sure that everything is covered, particularly when you've spent the last three weeks looking at the same set of equipment?"

Comments

Teach

[MrResistor]

Teach it to someone else and base the documentation on their notes, or even better have them write the documentation.

I'm not suggesting this as a lazy-man's solution or a way to to delegate all your work away. Your intimate knowledge of the installation makes some things seem obvious to you that would never occur to someone else. The person you're teaching it to is approaching it from the perspective of someone who knows nothing (beyond what's considered required knowledge for the position) and their notes will reflect that. You don't have to wrack your brain trying to figure out what the reader will need to know, your student will ask. If you really want it solid, have your student repeat the process with someone else.

The best documentation/procedures I've encountered were written this way, and it's become my technique of choice when faced with a similar task.

Use a wiki with your students

[plsuh]

I'd like to second this comment strongly. Teaching the system to someone else (or better yet several someone elses) and using their notes is definitely a good way to generate documentation.

Using a wiki, I have found, is a great way to generate a collaborative set of docs. Like another poster suggested you want to use hyperlinks very liberally, something which is easy to do on a wiki. In addition, everyone can write stuff down and edit each others' writings to add clarifications, extensions, improvements, etc.

If you have enough people to make it worthwhile, you can also establish access levels on most wikis. The guru(s) and the tech leads can all write to the wiki, while first-line help desk folks get read-only access.

--Paul