Debunking 5 Network Documentation Myths

Steve Lamont
By Steve Lamont November 20, 2018 11 minute read
Steve Lamont is a senior marketing manager at NetBrain Technologies. He has been an in-house content editor writing about operational and information technologies for over 10 years.

Everybody knows how important it is to have accurate network documentation. Yet almost nobody has it. Most network teams have come to accept this situation as just the ways things are.

But as teams face increasing pressure to be more agile, productive, and efficient, the status quo will no longer pass muster. It’s time to rethink network documentation and debunk some common myths.

Myth #1. Good Documentation Takes Too Much Time

Keeping documentation up to date for a large network could be a full-time job in itself. The sheer volume, velocity, and variety of changes make accurate documentation a Sysphean task. (Sisyphus was that guy in Greek mythology who had to roll a boulder up a hill, only for it to roll back down when he neared the top, for eternity.) A recent survey reveals that 61% of network engineers say that up to half of their documentation is out of date, with 44% indicating that it’s been over a month since they last updated their network diagrams. The #1 reason? It simply takes too long.

61% of network engineers say that up to half of their documentation is out of date, with 44% indicating that it’s been over a month since they last updated their network diagrams

Just keeping track of all the devices we have across an enterprise network is hard enough. Then throw in all the individual configuration changes we make on a regular basis.

Most best-practices gurus tell us to “document, then implement.” Sound advice, but it’s almost never followed in the real world. As network engineers, once we know what to do, we just do it. Sure, we tell ourselves that we’ll write it down later. But usually daily fire-fighting and constant pressure to do everything faster, faster, faster gets in the way, and “later” never comes.

Automatically Document Every SiteNetBrain automatically discovers, organizes, and maps all your sites into a single interactive diagram.

How NetBrain debunks the myth: NetBrain’s Dynamic Maps document your network automatically. An intelligent network discovery engine “learns” your entire L2 and L3 infrastructure — routers, switches, firewalls, load balancers, and more — as well as any endpoint with an IP address. Dynamic Maps are built from regularly “benchmarked” live network data, so anytime there’s a change to your network, the maps are updated automatically. Unlike SNMP-only diagramming tools, NetBrain collects CLI data across all devices so you have always accurate, always up-to-date documentation of all topology, design, and configuration variables.

And you don’t have to lift a finger.

Myth #2. Trying to Combine Physical and Logical Diagrams Creates a Mess

A single network environment really needs a handful of different diagrams—a physical diagram, plus maybe three or four logical diagrams mapping the traffic flow. Let’s say each distribution switch has a bunch of routers, firewalls, and load balancers connected to it. Trying to show all that on a single static physical diagram without it becoming a cluttered — and unusable — mess is nearly impossible.

Traditionally, physical and logical documentation is split up into two or more separate diagrams. The same equipment supports a lot of different stuff, so trying to show VLAN and VRF information as well as physical connectivity between the access, distribution, and core layers gets real messy real fast.

2. View L2 and L3 Topology on One MapView L2 and L3 topology on the same Dynamic Map.

How NetBrain debunks the myth: Dynamic Maps are far more than automatically generated and updated topology diagrams. They are in essence a user interface for visualizing all network information. That is, NetBrain’s auto-discovery engine learns your network the same way you would — by logging into every device and issuing CLI commands to understand design and configuration (and with the new SDN module, via API, intent). Through this deep discovery, NetBrain builds a mathematically modeled digital twin of your network, so no matter what part of the network you want to map out, all the data is already captured and gets embedded within the map. All you have to do is toggle on or off a specific view you want to see (L2, L3), and the map shows you all relevant data and interconnections — physical or logical. You don’t have to shuffle between individual diagrams or cobble together CLI output.

Virtually everything you could ask for is just a click or two away.

Myth #3. Documenting Things Likely to Change Only Creates More Work

The argument here is that we should document only what we can commit to keeping up to date. In theory, that makes sense. If we let our diagrams get stale, they’re almost worse than no documentation at all. Sooner or later someone will rely on obsolete documentation when troubleshooting and wind up wasting valuable time going down a rabbit hole.

The conventional wisdom isn’t saying that the ever-changing information is not needed, but rather that there are better places to retrieve the information than a diagram — usually via the CLI. Documenting frequently changeable details on static diagrams is shoveling sand against the tide.


IPv6 Routing Protocols on a network mapNetBrain automatically decodes configuration files and CLI data to visualize design attributes on a Dynamic Map.

How NetBrain debunks the myth: We actually take the opposite position: that a map is the best place to document things likely to change. And by “map,” we mean a Dynamic Map. We agree about the futility in trying document these details on a static diagram. We agree that the best source of accurate information is the CLI. But NetBrain automatically visualizes that high-fidelity CLI data in context right on a Dynamic Map. If you’re troubleshooting or responding to a cyberattack, you need the most accurate information immediately. You simply can’t afford to spend time crawling through the CLI to get the updated documentation you need to figure out what’s actually going on.

A map is the best place to document things likely to change.

Myth #4. Documentation Is All About Devices

“Network documentation” is one of those terms where if you ask 10 different people what it means, you’ll get 15 different answers. Everybody agrees that it comprises information you’d put in a Visio diagram or an Excel spreadsheet — physical topology, logical connections, IP addresses, MAC addresses, hardware inventory specifics — as well as configuration templates. In other words, data about devices that give you visibility into the design and configuration of the network.

Sometimes (and a lot less often than you’d think), case notes or procedures about how an individual issue involving a specific set of devices was resolved are documented in three-ring binders or wikis. But these playbooks are still primarily focused on devices.

Rarely what does what we consider “documentation” extend to capturing findings of in-progress troubleshooting. All too often, the results of an initial triage diagnosis are not recorded in a way that enables a next-level engineer to see what steps have — and have not — already been taken. Usually you get an e-mailed data dump, which you have to pore through in “stare and compare” mode. You have to essentially repeat the same analysis that was already done. In fact, most of us find it more efficient to simply start again from scratch.

EXECUTABLE RUNBOOKSEveryone can digitize their particular expertise into Executable Runbook workflows (no special programming knowledge needed).

How NetBrain debunks the myth: We believe that good documentation is really all about the ability to transfer knowledge that enables faster, effective decision-making. Truly useful documentation tells you not only how but why things happen.

That means documentation needs to capture both domain knowledge and subject matter expertise. Data about devices — what is traditionally considered “network documentation” — is only part of domain knowledge. Domain knowledge would also include understanding how your applications work together and the baseline performance of your network: information unique to your particular network. Subject matter expertise, on the other hand, covers know-how that’s applicable to any network: understanding specific technologies and protocols (SDN, multicast, BGP, QoS, etc.) and how to troubleshoot them.

NetBrain’s Dynamic Maps decode domain knowledge and visualize it on an easy-to-understand interface. Our Runbook Automation technology applies human knowledge — the subject matter expertise — to the domain knowledge. Your top experts’ know-how and “tribal knowledge” is captured automatically as part of the documentation.

Relatedly, these Executable Runbooks automatically capture the results of analyses and document them right inside the map. You avoid the time-wasting duplication of effort, and you have a way to easily share key information among and within teams.

Documentation then moves beyond data about devices to become actionable intelligence.

Myth #5. You Can’t Keep All Your Documentation in One Place

The old-fashioned notion of building and maintaining a library of diagrams is clearly no longer realistic.

For a network of any size, dozens of Visio diagrams get created every week — usually for an immediate problem at hand — which may or may not get filed in some central repository. But anyone who’s ever tried to maintain their network documentation on a Sharepoint server (or any other mutually maintained central location) knows how fast the project devolves into a hot mess. It soon starts to look like your kitchen junk drawer, or only the people who placed something there can find it. Wikis are better, but they too can out of hand pretty quickly. You simply can’t find the diagram you need (if it even exists) quickly, and usually the tagging or indexing taxonomy is inadequate (or again, nonexistent) to let you lay your hands on any previous post-mortem or how-to procedural guidance.

NetBrain’s dynamic documentation system captures both domain knowledge and subject matter expertise in one place.

How NetBrain debunks the myth: NetBrain has developed a system for dynamic documentation. It’s essentially a “documentation creation engine” that automatically decodes the network and visualizes pertinent network information on a contextualized Dynamic Map that can be generated on demand. This same Dynamic Map is a container for Executable Runbooks that codify human expertise — the network hero’s know-how.

Think of it this way: Dynamic Maps are where you see all the topology, design, configuration, performance, and other statistical/data documentation. Executable Runbooks document what you’d do with that information, the workflow steps you’d perform to accomplish the task at hand. Things like mapping a particular traffic flow from source to destination, checking for speed/duplex mismatch, identifying increasing interface errors, finding duplicate OSPF IDs or misconfigured AS numbers for a BGP neighbor connection — virtually any task, or step in a workflow, can be documented within a Runbook. And a Runbook doesn’t just document the procedures, it actually executes them.


Conventional wisdom holds that, in general, you need to keep your network documentation narrowly focused so that a single change doesn’t require you to update dozens of individual diagrams. Usually you wind up with diagrams that are a shambled mess with too much information, or very clean diagrams that don’t have enough information to be useful.

Dynamic Maps completely upend that state of affairs with dynamic documentation. Virtually any network information — what we traditionally think of as “documentation” — can be toggled on or off in a Dynamic Map, for whatever part of the network (or all of it) you’re dealing with.

But good network documentation embodies more than just data about devices. Your particular network’s baseline performance is also a key element in documentation. In fact, any domain knowledge about your individual network should be documented and immediately accessible to anyone, not just a chosen few network heroes. Dynamic Maps have all this domain knowledge embedded, just a mouse click or two away.

NetBrain also documents subject matter expertise: all the “tribal knowledge” that lives inside the head of your network heroes. In today’s increasingly complex environments, no one person knows everything about the network. Usually the deep know-how about troubleshooting BGP, multicast, QoS, etc., is spread out among different people. NetBrain’s self-documenting Executable Runbooks capture, digitize, and share the steps your experts take to address issues.

The underlying value of documentation is the ability to quickly transfer the information needed to make smarter decisions faster. Documenting how to solve problems is just as important as documenting what the network looks like.

Automated Network Documentation White Paper
Learn more about NetBrain’s system for dynamic documentation in our thought-leadership white paper Rethinking Network Documentation for the Modern Age

Get the white paper here