Go back

What Network Documentation Is NOT

December 10, 2018

There are many reasons why we document our networks. For instance, we know that documentation helps with the execution of critical network tasks such as troubleshooting and software management. We also document our networks to understand its underlying design and to keep a baseline topology for reference as new projects come up. We use documentation for training new personnel, to capture knowledge for later use and to adopt best practices. Lastly, we use network documentation to prove adherence to regulatory compliance.

network documentationIn practice, a lot of these discrete documentation efforts fall short due to the inadequacy of current network documentation tools and the tediousness of the tasks themselves. We get it, documentation is incredibly helpful and necessary for the smooth operation of the network, but it is not glamorous work at all, and it usually gets pushed down to the bottom of the ‘to-do’ list. Recently we defined what having a well-documented network means in the era of increasing network complexity and constant change. We have highlighted the inadequacies of traditional network documentation methods and tools (static diagrams, old playbooks, and unruly wikis) to meet this new agility required by the new networking paradigm.

Beyond the obvious problems that traditional network documentation present (manual effort, hard to keep up-to-date, incomplete, etc.), there is another set of long-held views about documentation that are getting in the way of teams deploying a more effective, holistic and practical solution for documentation. We acknowledge that each one of these elements is valuable in the network documentation puzzle, but by themselves, as they’re often referred to, they do not fit our recommended definition of intelligent network documentation. Let’s review three of these concepts that come to mind:

Visibility means different things to different teams but generally speaking, visibility informs teams what is happening in the network at a given moment in time (e.g., interface performance, packet flows, etc.). Network visibility is not network documentation because, without a baseline to compare performance data to, visibility is limited in value. The real question should instead be “is this performance normal?” To answer this question requires both visibility and a historical data point for comparison.

“Without a baseline to compare, network visibility is not network documentation.”

Having a complete list of network assets is essential for specific projects, but it only represents a small fraction of the organization’s domain knowledge (knowledge unique to the organization such as how your network is connected, critical applications, baseline performance, network design, topology, etc.). To be able to execute everyday tasks effectively, network teams need more information about devices, connections and live network data than a long list of assets. For example, an inventory list lacks context in describing the underlying design intent which would be valuable to guide an engineer through a troubleshooting incident. For this reason, inventory represents an incomplete view of network documentation.

Proactively Guard against Misconfiguration with NetBrainTo be useful to the network team, a well-documented network design should articulate the relational context of devices, protocols, etc. For example, what does the BGP design look like? Where are the route reflectors? What is the relevant BGP config? How do I troubleshoot this specific instance of BGP? Without this relevant correlation, configuration is raw data without expressing the intent behind it. It is another essential piece of the domain knowledge puzzle, but it alone does not constitute actionable network documentation.

Visibility, inventory, and configuration are vital data points that have a place within the overall network documentation realm, but they need a documentation system that places them into context when it matters, like during everyday network tasks.

“To be useful, visibility, inventory, and configuration need a documentation system that places them into context when it matters, like for  executing everyday network tasks.”

Networks will continue to evolve and change, and as they do, they will require agility from network teams. A new set of skills and tools are needed to meet this agility, along with a shift in mindset about network documentation. An intelligent system can help to effectively take the sting out of documentation with a new, effective approach to capturing network know-how. Don’t get bamboozled with network documentation tools that promise visibility without benchmarks, lists of inventories or device configurations without context; these critical elements can only help you when they work together.

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