The Importance of Network Documentation

The importance of network documentation becomes very clear when you have to sit down and troubleshoot a network from top to bottom. Or when there’s a changing of the guard at your company. New management wants to see what you’re doing with your network. Or new IT staff need to be brought up to speed quickly.

It could be time for an audit, and you’re left scrambling for documentation, or leadership is embarking on future planning and they’re asking for detailed reporting on the current growth of the network. In these kinds of situations, any shred of network documentation is like found gold.

What is network documentation?

Network documentation is the written charts, drawings, records, and instructions of networking procedures, layouts, and information on your l installed production network. It’s not the technical documentation from a vendor on how a specific product works or how it’s installed.

Good network documentation is vital to a smooth-running organization. Getting it right can mean the difference between a network with minimal errors and downtime, and a network that costs someone their job.

Many times, you think of documentation in a traditional centralized organization with giant three-ring binders. And you may have some of this. But effective documentation is going to typically consist of two buckets — “how it is” and “how to do it”:

1. Your first general grouping will be documentation that consists of instructions on how a network is set up and how it works, such as a knowledge management database defined in ITIL.
2. The second group can be seen as your “how-tos”, often referred to as standard operating procedures (SOPs) or processes. These are detailed plans or procedures for day-to-day operation and maintenance, best practices, and FAQs—what’s unique and tricks you’ve learned along the way.

You should also have documentation that shows your IP address scheme and IP address allocation plan with subnets, used addresses, and available addresses. For some businesses, this may be as simple as a spreadsheet, while for others a full IP address management (IPAM) system is implemented. A good network engineer is going to be managing IP addresses on a regular basis.

Another area to document is a physical representation of how your server racks are laid out, with details such as server names, models, sizes, and connectivity.

As well, a good cloud architecture diagram will help you understand how to connect to your cloud services and how traffic flows in and out.

You’ll also need a cabling diagram to understand how cables are built out in your network. What kind of cables? Where do they enter and leave? Connectors and specifications?

All of this documentation feeds into a good disaster recovery plan. What do you do if there’s a disaster? How do you recover from it quickly? Assume there’s no one left from the original team. How would the replacement team handle it?

Why network documentation is important

Imagine this scenario: You’re a network engineer new to a company, and after a series of issues, the decision has been made in your organization to drop some serious budget on a major upgrade to your infrastructure (recommended, of course, by your hardware vendor).

As part of your due diligence, you ask for documentation: network drawings, inventory, and anything else that could help determine if this was the right solution. Lo and behold, you discover there’s no real documentation. Those making the decisions, and the vendors, are new to working with the company, and this is an inherited problem.

These situations occur all the time. The previous network admin may not have documented much of anything, and now you’re stuck trying to fix the problems. Without documentation, you’re at the mercy of any third party who wants to sell as much stuff as possible to the customer.

In this scenario, you end up creating some pieces of documentation for the organization based on the rough sketches and network inventory you’ve done in the little time you’ve had. (Pro tip: as a network engineer or network admin, make sure you are taking notes consistently. This is the beginning of good documentation.) While your documentation isn’t 100% complete, it’s enough to get the message across to management that you don’t need to spend all this money on new equipment.

Moral of the story: Without detailed network documentation, there’s a potential to waste a lot of money.

Key benefits of network documentation

Let’s look at the key benefits of network documentation so we can understand why it’s so important. Never sell this function short. It should be considered part of a network engineer’s job from day one.

Visualization

Keeping a good set of network documents with diagrams of server racks, architecture, and topology gives you network visibility so you can see what’s happening on your network, understand traffic flows, and see bottlenecks.

Troubleshooting

Troubleshooting a network problem without good documentation is like shooting in the dark. You have to know what you have, where you’re going, and where you’ve been to properly troubleshoot your network. Documentation does this for you. When you’re in a problem situation and you need to resolve it fast, good documentation is going to help. Uptime on your network depends on this.

Think of the last time you had a performance issue on your network and couldn’t figure it out. And how easy it is to miss little details along the way. The ability to see and visualize these traffic flows is invaluable.

Standard operating procedures

Documentation is one of the critical elements to success with process and procedure. You can’t maintain SOPs—the goal being to keep processes consistent, effective, and efficient—without good documentation. Everyone will do something in a slightly different way. If you don’t follow good documentation, your procedures (and possibly your outcomes) will be different every time. The goal is to create success, document it, and then be able to recreate it consistently every time.

Budgeting and forecasting

Networking and network technology planning require the purchase of software, equipment, servers, and services. These are expensive technologies that are required to be planned and budgeted for in advance. These plans need to be justified to management. Without good network documentation, you’re just guessing.

Saving money

Your resources are scarce, and the best use of them is going to rely on keeping detailed network documentation. This isn’t a process that should be left to chance. The leaner you need to run, the more you’ll need to save money. And that relies on good documentation.

How do you share network documentation?

The entire purpose of detailed network documentation is to share this information effectively throughout your organization. At the same time, we need to have an eye on security and not share valuable information with the wrong people.

The process of sharing network documentation starts with assigning responsibility to the person who generates it. There should be a simple policy rule that says after each networking project, no matter how small, it’s not done until it has been documented and updates are made. Then this finalized documentation should be centrally published to the authorized parties so they can incorporate it into their production activities.

Time should be given to accomplish this critical part of the task at hand. Encourage network engineers and technicians to take careful notes on meetings and whiteboard sessions and turn them into drawings for project plans. Then, share with team members to ensure they are accurate. Go through implementation using the documentation as a work in progress. And as the final step, update to make the latest changes.

When all this is done, documentation should be shared only with individuals within the organization that need to know, not published on public forums or any public-facing resource. Documentation can be shared with vendors on an as-needed basis but not distributed to them in hard copy or electronically.

Items you should document

Server rack diagram

All server racks should be completely documented so you always have an accurate picture of the data center, as most of the time you won’t be there. Make sure you have all components including power strips and monitors. You should know exactly how you connect to the server rack.

Cloud architecture diagram

This diagram will show you where you connect to your cloud services and how. You should show all connections and speeds. Remember, compliance and security should always be top of mind. Documentation of your cloud architecture will help with this.

Network topology

Your network topology is the fundamental building block of all network architecture tasks. It’s the one you start with, and it’s the one that you’ll build your other documentation components with. This will be your master plan. Its function is to allow you to visualize exactly how your network is set up. Once this is complete, it may show you things you weren’t aware of.

IP address allocation

IP addresses are a critical resource for a network engineer and shouldn’t be left on a single spreadsheet on one person’s laptop. It needs to be an active, clean table of information that releases old, ghosted addresses and keeps these addresses ready for use. Taking into account subnets, subnet sizes, and dynamic address allocation. All of these functions allow for effective network planning.

Recovery plan

The recovery plan is the responsibility of every IT and networking manager. It should also be an active part of the everyday activities of the networking engineer. These questions should always be top of mind, “What if that technician or this engineer was not here tomorrow? What would I do? How would a replacement do their job? How are backups done? How are they used? How are they restored? Has it been tested?” This extends all the way to the point of having lost all your personnel or your facility. How would you recreate a working production network again? All these documentation components feed into this recovery plan.

Keeping detailed network documentation is very important. The fact is many companies don’t do it or don’t do it effectively. Its importance usually becomes very apparent when there’s a serious problem, or when there’s a loss of personnel.

Start your documentation today. Build network documentation planning into your process and procedures. Plan for it now. Get your team together and on the same page. Start with your network topology. Make sure notes are being taken at network planning meetings, whiteboards are being recorded. Then incorporate documentation into the planning and the implementation process.

And finally, have a policy that states a project is not finished until the documentation is finished and approved. You will hold on to this documentation tightly after it is done and be happy you have it.