Good, bad or ugly, network documentation can make or break a network. Even if you are the one that designed, configured and installed every piece of the network, the network documentation is important. We all forget things, and we definitely forget things that we only do once in a long while. Almost everyone has come into a new job and found that the previous network documentation is a bit lacking or confusing.
In education circles, Bloom’s Taxonomy is used to describe the different levels of learning. The levels defined in the taxonomy are (in order from lowest to highest) remembering, understanding, applying, analyzing, evaluating and creating. Remembering is simply that the student can regurgitate facts that they memorized. Understanding takes the student to the next level of being able to explain the facts that they’ve memorized. Applying means that the student can use the information to do something new such as to solve a problem. In the analyzing stage, the student can take the information and examine and compare it. At the evaluating stage, the student can justify a decision or opinion based on the information. Finally at the creating stage, the student can produce new works.
Just like Bloom’s taxonomy, I believe that network documentation has different levels of being.
This would be the basic nuts and bolts of network documentation. Lists of IP addresses, circuit IDs, password safes, and configuration archives are examples of this information. Lots of useful information, but at this point they’re not necessarily all that helpful. Think for example of being thrown into a network down situation and all you have about the network is a list of IP addresses. That tells you something, but it’s hardly a good place to be when the network is down. A list of IP addresses doesn’t tell you the topology or any of the protocols in play. It would sort of be like getting an IKEA product with just a parts list and trying to put it together. Yes it could be done, but not easily.
Obviously our lists of things are important, but not necessarily all that useful. We need to come up with a way to give the person using the documentation the ability to understand how all of the facts relate to each other. At this point, a picture is worth a thousand words. Time to break out Visio or your favorite drawing tool and put the network on paper. Now the information is more usable for basic troubleshooting. We’ve identified the various parts of the network and how they are connected. In the example below, a layer 3 diagram is shown, but it is also a good idea to have a layer 2 diagram as well. This is especially true in networks that may have hybrid L2/L3 uplinks.
Besides diagrams, procedural documentation often accompanies this level of documentation. These are the HOWTOs. Often times they will be an ordered list of do this, then that. Hopefully they will also have screen shots and other illustrations to help another person understand the process.
Design and Rationale
At this level of documentation, the goal is to explain how the network came to be the way it is currently implemented. What choices were made in its design? Why were those choices made? Were there business reasons for compromises from best practices? Items that should be included in this part of the documentation include routing protocols, first hop redundancy protocols, layer 2 versus layer 3 uplinks, and device choices. This type of documentation can prevent a lot of head scratching for engineers new to the network. It can also provide a good basis to review the current network design if a previous decision’s key influence has been eliminated. For example, often when two companies merge, their networks are jammed together quickly. Down the road, some of the decisions made in the merger need to be rethought as the new combined network becomes more integrated.
This is the level of network documentation where most of us fail horribly, myself included. The design and rationale information usually is very accurately portrayed in various documents during the build out, but it is never formalized and put in an as-built document for later reference. To add insult to injury, five or ten years down the road, when the insight from these documents (that no longer exist) would be useful our main memory (brain) decides to have CRC errors. Winston Churchill is often quoted as saying, “Those that fail to learn from history are doomed to repeat it.” Unfortunately in networking when we forget the reason for the design, we’re often doomed to repeat something that will cause a network outage or user headaches.
The flip side is often true as well. You may find by reading the documentation about the design and rationale of a network that the assumptions made are no longer valid. “It’s the way we’ve always done it,” is not a good network engineering methodology. Could you imagine if we still built gigantic flat Layer 2 networks in large campus environments?
Documentation Pledge for Packet Pushers Everywhere
We all know that documentation is important, but most of us our guilty of forgetting to do it. Let’s band together as Packet Pushers and pledge to each other our solemn obligation to document everything.
I, <state your name>,
Do pledge to faithfully document my network,
and keep it updated with all changes,
including little ones I think I’ll never forget.
I also pledge to leave behind good documentation,
for whomever may come after me.