We know we need it, we know it’s important, but we just can’t seem to make the commitment to do it.
The purpose of this blog is to give ideas of what and how things should be documented.
The documentation should be available and easy to understand for those who refer to it.
Remember that documentation is for a wide audience, although some technical documentation may be geared towards the technically inclined.
I think more in OSI terms and have much of my documentation that maps to a layer of the OSI model.
Physical Layer -
Documentation for this Layer would include building maps that would show cable numbers and have the physical cabling mapped out. It would also include wireless heat maps to show the wifi coverage of a building.
A Hardware and software inventory of my network nodes and wireless access points may also be a part of my documentation. There are several tools that can assist you in not only creating but maintaining such documentation.
It’s much nicer to run a report of an SNMP tool to learn your software versions than it would be to type “show ver” on 100 devices. VoIP or POE budgets may be another item to include.
Data Link Layer -
Here is where you would want good topology maps. There are various applications that can help in mapping your Layer 2 topology maps. This is the data link layer so the maps should show network links and how everything links together.
Applications that take advantage of SNMP, CDP and LLDP will be of great worth in mapping your Layer 2 network. Be sure to include redundant links and EtherChannels in such a map.
Network Layer -
This would include your IP addressing assignments plan for your network, including summarization plans for LANs and WANs. There are various IPAM applications that will help you in documenting your IP addresses. IPAM tools are great because they will help you track the ever dynamic assignments of today’s IP addresses. I have also used Visio Maps that show a Layer 2 layout of the network, then added IP network advertisements so we can see on a map where networks reside, where summarization is being used and it shows me what needs to improve.
Transport Layer -
Knowing what ports your applications use is a must if you are a Firewall Admin. Even more important is knowing what applications may use those ports. I used to like to clump a bunch of ports into service groups to make my rule set look cleaner and smaller. It was a terrible idea for documentation purposes, though. I started making rules for applications and used the Description field for rules so I could remember what the rule was for. NetFlow logs would also be a great Layer 4 source of documentation.
Session Layer -
This is the layer where I have load balancers in mind and where I would keep load balancing services documented. Many times, the configs of load balancers may be sufficient. What are the VIPs of your load balanced services? Does the load balancer host the certificate for your application or is it hosted on the server? What are the sticky bit timers on each virtual service? All good things to have documented.
Presentation Layer -
I would not expect someone to document all of the file types an application would support, but in the Presentation Layer, one item that comes to mind is encryption. If your application requires certificates, this would be a good thing to have in your Presentation Layer documentation. Not only that, but a reminder of when your certificates expire so you know when to renew them. Having a system break or perform undesirably because of an expired certificate is not a fun place to be.
Application Layer -
Here, you would have your applications documented, the owner of the application, the application version, support contracts for that application, etc. Now when I say owner, I mean the person of the organization who has ownership over that application. Take Email for example. Who ever is responsible for operating and maintaining your email system would be the owner.
Honorable mention to Layer 8, having good notes about meetings, what is discussed, who made decisions, and who owns assignments with due dates are all things that should be in these documents.
Too common is the meeting where things are discussed but nothing is followed up on because no one remembers what was discussed or agreed to. Keeping good notes from meetings and referring back to a previous meeting is the way documentation is used to keep meetings productive. Recording meetings is a way to document such meetings. Documenting meetings is not just a way to hold others accountable, but to hold yourself accountable as well.
If I don’t document meetings, I am not going to remember everything discussed. I just won’t.
NMS, IPAM, Visio, OneNote are all excellent tools to help you with your documentation. Now, you don’t have to organize your documentation by the OSI model as I have described.
Others may organize by function, say, all of the documentation for Data Center, Wireless, Security, VoIP, Routing & Switching, etc.
Organizing documentation in these functional areas also helps keep Documentation organized.
It may help in larger organizations that have dedicated R&S, VoIP, Security and Wireless people to keep the documentation of their own functional areas.
I have seen others that organize their documentation in 3 tiers.
Core, Distribution, and Access.
Once you have your documentation, keep it up to date.
Once outdated, you are reading a history manual, not a network document.
Incorporate in your change control procedures so that when a change is made, part of the change is updating the documentation where applicable.
No matter what role you play or how you organize it, good documentation is vital to the success of preparing, planning, designing, implementing, operating, and optimizing any network