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.

Managers and documentation

[Anonymous Coward]

There was this job I once had... it was a large project, and design work was mostly done and implementation had begun when I joined. I was astounded at the quality of the documentation: major design decisions and justifications, ideas that didn't work, things to look out for -- all documented. Not just that: it actually was updated as things changed! This inspired me to keep a diary of my first few weeks at work, which contained things like the organisation of the source code, the build system, environment variables necessary for developers -- the things that people already working on the project know but that might have been opaque to newcomers. Yes, we were proud of the system, and of the documentation.

Now we skip forward about a year, when it's time for annual reviews. One of the things that the moron manager dinged most people for was the quality of the documentation! I marched in and, in a high dudgeon, demanded to know the meaning of the outrage. The documentation was bad, he replied, because marketing and tech support couldn't figure out what the thing did. I tried to point out the difference between documentation for users and for programmers... I should have saved my breath.

There were other problems with this yahoo, of course, and most of the dev team quit soon after. The company went under a little after that.