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.
first, label everything clearly. 2nd, document what you've done. print documents, in case there's no computer around to read them on. screenshots or logs of what you typed and have done is better than handwritten notebooks. 3rd, train someone in the Why and How of a system and it's response and they'll figure out the What on their own, usually. also, check out this article at kuro5hin and then do what seems more useful.
FreeBSD for the impatient.
Especially in network documentation. Nothing beats back a snarl of wiring (even if you were neat, you know by the time someone else is going to have to work on it, it will be a mess) like some old-fashioned line drawings. And remember, only half the documentation is what you are writing down--the rest is in clear labeling of cables, equipment, and machines.
Aside from that, what some guy said above is perfect--a broad-sketch overview, a sort of narrative description of how everything works and fits together, and then detailed drill-downs in specific systems and sub-systems. No point in forcing someone to go through twenty paragraphs of detail when all they need to know is what Router A is supposed to connect to. The overview is often the most valuable part of the documentation.
I just use a basic outline format usually, but as long as there is a table of contents and some sort of logical progression to it, I don't think it probably matters too much.
Good documentation is what really distinguishes professionals from amateurs in this business.
No relation to Happy Monkey
I've just written a short book on this. Documentation for SysAdmins, SAGE/USENIX's 11th short-topic book, should be available shortly (probably at LISA 2003.
.@.
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