Go back

What’s Missing From Your Network Documentation?

Dec 5, 2018

When you think network documentation, what comes to mind? Most of us immediately think of our typical network topology diagrams. While some organizations have the luxury of a repository of up-to-date Visio diagrams, many make do with quick sketches done on notepads or a whiteboard by their network guru right before he leaves for his next gig.  With today’s complex hybrid networks, it is as important as ever to ensure the network is well documented.

But what does that even mean, “a well-documented network”?  Yes, of course, up-to-date topology diagrams play a large part. But there are a number of different elements of network documentation that every team should have available to them to make them be more efficient.

IP Address Management

Having visibility into the address space in a network is a necessity when doing a migration or network merger. Gone are the days where this can be managed by a shared Excel spreadsheet saved in a central location. Even with small projects, collecting and keeping this information up to date manually becomes problematic. You would think that four people could easily manage a simple spreadsheet of a /24 network, right? Well, that’s not always the case. Based on my past experience, it only took a couple of days for “conflicting copies” of the same spreadsheet to appear. Not to mention, one engineer deployed around 10 systems but never updated the spreadsheet. And for the existing IPs in use, we had absolutely no insight into how exactly they were connected to the network. It only took three days for our “single source of truth” spreadsheet to be deemed untrustworthy, and we had to waste hours validating and updating this spreadsheet manually before proceeding.

What's Network DocumentationNetBrain’s One-IP Table automatically documents and updates key information for all IP addresses in your network.

NetBrain’s One-IP Table keeps a record of the physical connectivity of all IP addresses in the network, including L3 interfaces to switch ports as well as end systems to switch ports. This data is retrieved during L2 topology discovery and is kept up-to-date automatically as the network changes.

Network Documentation PlaylistOne-IP Table is fully searchable — here, we’ve filtered results to show only the LAN segment.

The One-IP Table is fully searchable database: just enter any data point — or even a fragment of the data — and NetBrain filters the table to display only the relevant results. You can simply search for an IP or MAC address, and instantly see where it connects. This is a lot easier and more reliable than manually creating and maintaining a spreadsheet. And it’s a whole lot faster: you find out how things connect in literally a matter of seconds.

Historical Data

compare actionHistorical data is a powerful form of documentation for network engineers. When a network outage occurs, the first thing out of a network engineer’s mouth may well be, “Well, what changed?” Does your organization have a clear picture of what the network configuration looked like last week, before a major outage?  What about how your traffic was routed last month? Let’s say you are pushing a routing change to your core router. This may impact the routing tables of connected devices even though no configuration change is being directly pushed to them. Without a baseline of the network, engineers may struggle to find the root cause of an outage.

NetBrain provides an automated solution to baseline device configurations and device data. During the discovery benchmarking process, NetBrain collections configuration files, routing tables, NDP/ARP/MAC tables, and more from all your network devices. From any map, a one-click Compare function allows for a quick and easy way to see exactly which data has changed from a previous iteration of the network. Imagine having a side-by-side comparison, showing which routes were added or removed prior to a major network outage. This alone could save hours of downtime and frustration! Not to mention, NetBrain lets you keep historical records of any show command to use for historical analysis.

view route compare 2NetBrain’s Comparison feature provides before-and-after details of config files, data tables, and CLI command outputs. Here, we see the route table changes to the NY_Router.

Information You Don’t Even Know You Need

Often times, the most important network documentation to have on-hand is the kind you didn’t know you needed until it’s too late. Having accurate information available at your fingertips empowers engineers to make well-informed, smarter decisions about managing the network faster. What happens if one day a network change introduces a broadcast storm, and your team hasn’t seen this type of issue in years? How much time will be spent understanding the issue, brushing up on all the troubleshooting commands, and resolving things in a timely fashion? The last thing you need to be doing when there’s an outage is Googling for the right show command to get the data you need.

Working with network devices from various vendors requires engineers to learn each vendor’s operating system.

As networks grow ever more complex, it becomes increasingly difficult for engineers to efficiently collect and analyze data across the entire environment. Working with network devices from various vendors requires engineers to learn each vendor’s operating system. If your organization decided to switch from Cisco to Juniper switches, there could be some ramp-up time for engineers to troubleshoot efficiently. Even a couple of extra minutes spent collecting data manually could result in thousands of dollars lost during an outage.

OSPF WAN toploogy map

View the OSPF design automatically annotated on a Dynamic Map, including configuration, area numbers, ABR/ASBR, and more.

With NetBrain, data is saved and benchmarked within the platform using automation. Visualizing and decoding the network design doesn’t require device-by-device analysis using the CLI — it can be done simply by bringing up a map of a problem area, and overlaying configuration and topology data with a mouse click. Since NetBrain knows how to gather data from all major network device vendors, all relevant information is documented automatically and available on demand in a Dynamic Map. Using the NetBrain platform removes “the lack of visibility” pain that many engineers face, making them work smarter — not necessarily harder.

 Information from All Your Other Tools

It’s common practice for network teams to have a bunch of different “best of breed” network tools to manage their infrastructure. Think 24×7 monitoring, incident management, security, inventory management — the list goes on. According to EMA’s 2018 Network Management Megatrends Report, 72% of network operations teams use four or more tools, with 27% having more than 11 tools.

Often it’s the data that’s the most valuable aspect of these tools, but the information is hard to access because each tool exists as as a silo’ed “data island.” In fact, research has shown that without meaningful integration, the more tools you use, the less effective you are at managing the network.


The point isn’t that you have too many tools, it’s that they don’t talk with one another. To get all the valuable information they capture, you have to jump from screen to screen, navigate their unique interface, and cobble everything together (assuming you even have log-in privileges).

The most important characteristic of network documentation is the ability to transfer knowledge to enable effective decision-making. A key part of this knowledge is the information contained in your various tools. If that information is scattered across disconnected data sets, you’ll either miss a crucial piece of the puzzle or spend a lot of time connecting the dots to get clear insight into what’s going on.

The point isn’t that you have too many tools, it’s that they don’t talk with one another.

NetBrain, through its rich API framework, integrates any network information into a true “single pane of glass” interface: a Dynamic Map. Layers of NMS information can be toggled on or off right on the map. You can see performance details from a monitoring solution like SolarWinds or PRTG; any open tickets from, say, ServiceNow; security data from Splunk, Qradar, or other SIEM system — anything with an API.


While network topology diagrams are an essential piece of the puzzle, there is a lot more to a “well-documented network.” The value of network documentation is to enable knowledge to be transferred quickly, fully, and effectively so that we can make better, faster decisions about the network.

Key elements of network documentation not available in static diagrams include:

  • Accurate, up-to-date list of IP addresses
  • Historical benchmark data
  • Deep domain knowledge across the multi-vendor environment, available on demand
  • Network information from various NMS (monitoring, ticketing, security et al.), available in a single pane of glass

Having a well-documented network is a crucial factor in maintaining optimal performance, reducing MTTR, identifying security vulnerabilities, isolation cyber attacks, and validating changes and technology upgrades.

It’s time to re-define what we think of as network documentation.

Check out our latest white paper — no form to fill out! — Rethinking Network Documentation for the Modern Age.