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

OSI Model as a, um, model :-)

[moonboy]

I've done more than a little bit of this in my time. I've learned that as long as it is well organized and understandable, you can never document too much. I prefer a layered approach that coincides with the different layers of the OSI model. I begin with drawings from layer 1 on up, basically from cable, ports, card/slot, box, etc. [Physical Layer] to DLCIs (Frame Relay), VPI/VCI combos (ATM) [Data Link Layer] to IP Addressing and routing information [Network and Transport Layers]. I create numerous drawings in Visio and write documentation in Word (yeah, I know, MS). When appropriate, I import my Visio drawings into the Word document(s). You can even structure you document using the layers of the OSI model as well. Hope this helps a bit.