An Honor It Has Been

Picture this. A branch site decides that they want to manage their own IT resources, their own infrastructure, servers, and data and break off of the main network.


The IT consultant the branch office hired approaches and asks, “What kind of documentation do you have?” The response is either a blank look or a sheepish grin as the IT engineer points to his forehead and taps it lightly.


Does this sound familiar? Unfortunately, it’s far more common than any IT engineer would like to admit, be it a consultant who is asking for the information or the engineer who needs to provide it. I have personally been in both roles and have experienced the embarrassment and fear of not being able to provide documentation and the frustration and anxiety of not being able to collect it because it doesn’t exist.


Documentation. We know we need it, we know it’s important, but we just can’t seem to make the commitment to do it. Oh, we have good intentions, but time is not on our side, and in our busy lives as IT professionals, documentation seems to be the last thing on the list of priorities… until you are in one of the above situations and then the light bulb turns on and you wish you had some documentation available.


The purpose of this blog is to give ideas of what and how things should be documented. There really is no right or wrong answer as long as the documentation is available and easy to understand for those who refer to it. Remember that documentation is for a wide audience, not just IT geeks, although some technical documentation may be geared towards the technically inclined.


The CCDA mentions network audits and the various tools used to perform and document those audits. It gives some great ideas and teaches how documentation is a common theme in PPDIOO cycles of network design. For me, I actually think more in OSI terms and have much of my documentation that maps to a layer of the OSI model. For example:


  • Physical Layer - My documentation for this Layer would include building maps that would show cable numbers and have the physical cabling mapped out. It may 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. POE budgets, may be another item to include in your documentation.
  • 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.


Now, to give an 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. Think if every function was documented by OSI Layer!

I have seen others that organize their documentation in 3 tiers. Can you guess what they are? Core, Distribution, and Access. In reality, I probably use a combination of all of these. However you organize it, it's important to link these documents together some how. The OSI Layers all link together to give us a network, so our documentation should link together to show us the network.


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. I promise you that the extra few minutes while the change is being made is worth it. Speaking of Change control, things like TACACS accounting are great tools for documenting just that.


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.