Writing Good Network Documentation? 41
_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?"
Re:complex? (Score:2)
It also equals no advancement because you are too important in your current role. ie, your in a rut.
COMPLEX??? (Score:1, Funny)
Anyone that finds this network complex should not be allowed near the console! This is the most basic of internet connected network and identical setup can be found in hudreds of thousands of homes and small businesses.
None the less. Documentation is always a good idea. It should include a rundown of all services in use on the network
Docbook (Score:1)
Nothing you can do (Score:2)
Re:Nothing you can do (Score:2)
Re:Nothing you can do (Score:1)
Good Beetlejuice reference. I've not seen too many of those here on Slashdot.
Overview it (Score:5, Informative)
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.
Re:Overview it (Score:2)
well.... (Score:3, Informative)
Re:HOWTO: write bad documentation that looks good (Score:2)
Re:HOWTO: write bad documentation that looks good (Score:2)
I doubt it, that article has only been up for a week.
You know (Score:1)
OSI Model as a, um, model :-) (Score:3, Interesting)
Re:OSI Model as a, um, model :-) (Score:1)
nice comment, stolen straight from k5 (Score:2)
Teach (Score:5, Insightful)
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.
Re:Teach (Score:2)
You're going to need a backup anyway -- so that, for example, you can go on vacation -- so teaching him and using his notes to write the documentation will kill two birds with one stone.
I've used this technique on more then one occasion. Being forced to explain how something works really helps you understand what the heck you did to set things up and how they really work.
Once you train your backup(s), have them run your network or perform maintenence, upgrades, e
Use a wiki with your students (Score:3, Insightful)
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, e
Pictures! (Score:4, Informative)
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.
As a matter of fact... (Score:4, Informative)
I've just written a short book on this. Documentation for SysAdmins [sage.org], SAGE/USENIX's 11th short-topic book, should be available shortly (probably at LISA 2003 [usenix.org].
Not much complicated (Score:2)
Best guess, and what I try and do (Score:5, Informative)
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
Bad starts lead to bad finishes (Score:2)
For the great unwashed (Score:2)
I'm not real sure... (Score:1)
one thing (Score:1)
IMO, YMMV.
Re:one thing (Score:2)
if all of the systems you setup and maintain are well documented, you would be easy to replace... however if you're the one documenting them, that's a good reason to keep you around... sure you _could_ be replaced easily, but who knows if the person after you can be replaced as easily...
so in essence, removing your job security gets you job security... and no qualms i
Managers and documentation (Score:1, Interesting)
I don't care what you do... (Score:2)
Big things as well, like an online centre half the size of the main one we run, which no one thought to tell me about until their router died.
Most of these comments suck (Score:2)
Okay, here's the deal. There's not a whole lot of law out there to protect privacy. You could go after each Spamer, but that's like hearding cats.
That being said, they issued you a credit card. In order to do that they pulled your credit record. They were not authorized to do that. They are therefor in violation of the Fair Credit Reporting Act. Both you, and the credit reporting agentcy can collect money f