Slashdot Mirror
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?"
I overview the entire network, then overview the seperate systems, then go into intricate detail about everything i've done and why i've done it.
I do semi-detailed overviews to start because when I've needed documentation in the past, its been an emergency, and i've mostly needed it to know exactly what router X is connected to, basically how it is configured, and what it is used for, not the intricacies of the firmware pasted blatantly up front without any mention of what the router does.
do the documentation in HTML and hyperlink EVERYTHING that could possibly lead to a question or a footnote or any supplementary text. this is what hyperlinks are for but far too often i've seen network documentation handed to me as 5th generation photocopies that are near impossible to read. take your documentation to anyone that is covered by an NDA (if need be) and have them proofread your documentation. have him ask questions that he would ask if that network were handed over to him, and on his first day needed to find out why the WAN was down, but the wan router reported it as up.
then burn your documents on CD, and keep it close to your heart and any contractor that works for you.
that's what i do, but i'm paranoid. i've been the victim of poor or non-existant network documentation too many times to not be paranoid about it anymore.
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.
Under capitalism man exploits man. Under communism it's the other way around.
1. Download all of the documentation locally, especially for all networking equipment. Keep all patches/firmware upgrades locally so that in the event of a failure you have everything you need onsite to solve the problem. I once had a router go down, and the only copy of the docs we knew of was online... Good thinking guys... :-)
2. Do an analysis of what would happen for each piece of equipment if it failed. A list of steps to detect the symptoms. Essentially, a list of things to help trouble shoot it. Do this, also for major configuration settings that could be wrong (Gateways, DNS, firewall rules, routing rules). So essentially list what you think it would act like if a switch broke. If the router broke. If the DNS server went down. What it would be like if the proxy server crashed. What would happen if the firewall settings got mis-configured. How they could tell the tape backups didn't work. Things like that.
3. Put in place a system that will help to pull the configuration off the machines. Creative use of SNMP, nmap and something like NetSaint (now Naigos) will help you pull the configuration off the running network to see if you can identify failures or changes in configuration. Document how the configuration should be, and check it using those tools with alerts sent out when something looks wrong.
Kirby