Go back

What Does Having a “Well-Documented” Network Really Mean Today?

Jul 16, 2018

Documenting a network is one of those IT practices that has been done manually since the early days of networking. The term “network documentation” conjures visions of diagrams and stacks of dusty 3-ring binders full of processes, procedures and stale topology maps. At one point or another, network engineers have suffered through the painful process of updating these static diagrams and playbooks, sometimes from notes scribbled on the fly, as they try to troubleshoot a problem, answer questions about security incidents or look to meet new requirements.

In the era of IoT, Cloud, and Mobility, business units are demanding more and more of the network and the teams that manage it, while injecting a level of scale and complexity not seen before. The traditional toolsets and practices used by most network operations teams date back 20 years or more. We are starting to realize that when it comes to meeting new business requirements, visualizing hybrid networks and managing virtualized environments, “conventional methods” are no longer going to cut it.

We measure the value of network documentation by its usefulness in enabling network teams to store and transfer knowledge. This knowledge goes beyond merely recording IP addresses, hostnames, and logical connections; it must also effectively harness the tribal wisdom accumulated over the years by the subject matter experts, for use in the future. Network documentation is, therefore, a foundational element in critical IT workflows.


Isn’t it time we update our understanding of what a well-documented network is, considering today’s new requirements?


Most importantly, shouldn’t we adopt a faster, more effective approach to keeping the network documentation perpetually up-to-date, no matter the complexity?

The answer is a resounding yes, but truth be told, documenting a network – especially using manual methods – is not an exciting task, far from it. However, network teams can derive an incredible amount of value from having up-to-date network documentation. From saving time during troubleshooting to visualizing different areas of the network for service expansion to isolating an attack. So, let’s take a moment to understand the tenets of a well-documented network:



The value of network documentation is measured by its usefulness in enabling network teams to store and transfer knowledge.


The right map is customized for every task

Mapping a network area manually with information gathered from the Command Line to complete a critical task is inefficient and robs the engineer of precious time. When every second counts, having quick access to the right information within the appropriate context is as valuable as gold, or lots of bitcoin. Either way, reducing the time it takes to gather the information means network engineers can use their time for action.

We believe that for network documentation to be helpful, it must be accessed quickly, it must be relevant to the task at hand and presented in an easily consumable way, like in a Dynamic Map. Dynamic Maps have become the natural replacement of static network diagrams as they offer on-demand contextualized information about precisely what the network engineer wants to see. They are built from live network data, in seconds and can be customized for a specific task. The critical element here is time. Essentially, Dynamic Mapping enables access to the right map, with the right level of context, exactly when it’s needed. This makes it the ideal solution for assisting network teams with critical tasks.

The right map alleviates the need to harvest data from the CLI

Research shows that the average network team spends three-quarters of its time fixing problems. Some of this valuable time is spent simply wading through a sea of details that, although important, are unnecessary for completing the task at hand. Nothing is more distracting than dealing with the clutter of having too much information when only a small, relevant data set is needed to visualize an issue. The ability to focus on the right variables during a task can significantly help in condensing the time it takes to complete it.

The ability to offer the user several data views without having to harvest details manually from the CLI helps the network engineer to visualize the problem and get the contextualized information required to fix it. Having quick access to a mind-boggling amount detail that can be turned on or off with one click is an essential characteristic of useful documentation. We recommend that network teams consider visual tools with these characteristics when sourcing a network documentation solution, because they offer the right amount of detail when needed, alleviating some of the reactive troubleshooting pain. Visual tools like Dynamic Maps can effectively help to reduce MTTR and allow the team to become more productive in other areas.


The right network documentation tool provides a customized, graphical representation of the area of interest, without having to harvest data from the CLI.


Procedures are created automatically, as you work

Network teams conduct post-mortem reviews of every major network issue. However, documenting troubleshooting steps after the fact is a tedious practice. Teams are usually too busy putting out the next fire to record their lessons learned or troubleshooting best practices. A critical element in maintaining a well-documented network is having procedures that can write or update themselves, as the subject matter expert goes about their business of troubleshooting.

Executable Runbooks can help by self-documenting a troubleshooting process. Whether the expertise resides in islands of knowledge within a team or a single individual, Runbooks can help to codify this tribal knowledge by capturing expertise into executable steps as they happen, automating their use for the future. And best of all, this can be done without needing any programming skills. Executable Runbooks streamline the automation of any procedure and optimize collaboration among teams, effectively shortening the diagnostics and escalation times in future troubleshooting scenarios.


The right tool can enable network teams to document procedures and capture tribal knowledge as they work.


The right tool enables the visualization of any network data

According to research published by the Enterprise Management Associates® (EMA™) in the Network Management Megatrends 2018 study; network teams use anywhere between 4 to 10 tools to manage their networks. They have access to a multitude of data points, which are relevant to their day-to-day operations but scattered in a myriad of dashboards, behind disparate user logins. Visibility over key network assets or problems is fragmented at best.

To be a useful tool, information about the network must be relevant, quickly accessible and provide context for action. Consolidating essential data from a variety of tools into a single view can improve visibility and help network engineers accelerate the completion of critical tasks, such as troubleshooting a problem. A Dynamic Mapping tool that can extract vital metrics from other applications and present them graphically in a concise way will give network teams a significant advantage as they face new network challenges. Using the map as the coveted “single pane of glass” is the way of the future, and available today as part of a comprehensive plan to network documentation.

0.Rich APIs Integrate with Existing Workflows 850

A Dynamic Map that consolidates essential data into a Single Pane of Glass is an essential element in a comprehensive network documentation plan.


The right tool demystifies modern hybrid infrastructures

Software-defined networking brings the promise of increased performance to the enterprise. More agility in application deployment and resource utilization are among the chief benefits, but the learning curve is steep. Network teams struggle to document even what they have today since they can no longer put their hands on the physical hardware. This issue is compounded by the challenge to understand and document how application dependencies map to the network. Traditional methods to gather information -such as the Command Line Interface- will no longer work. As SDN becomes an ever-increasing part of the overall enterprise network, the inability to visualize assets or issues across multiple technologies could become a hindrance to smooth operations.

It is imperative that network documentation tools can reach the far corners of the network, no matter what form it takes. This ability to demystify and decode the complexity and abstraction of SDN infrastructures and present it seamlessly along traditional physical networks during the execution of critical workflows is a significant advantage. Having visibility across hybrid infrastructures will enable network teams to keep pace with increased demands and empower them to act quickly when required.

Engineered for Modern Networks 1

Network documentation must seamlessly present legacy and SDN networks.


Network documentation is the lifeline of the network team. An invaluable resource that can enable faster troubleshooting, resource optimization, network refresh, capacity planning, regulatory compliance and a better understanding of how to deploy new and emerging technologies. It can also support on-boarding new personnel and optimize knowledge capture and transfer. The days of static diagrams and stale procedures are over, this approach served the industry very well, but it’s tired and unable to scale to new challenges. Consider enhancing your understanding of what it means to have a well-documented network to include these tenets; these will help your teams to maintain agile operations well into the future.

Download our new white paper “Rethinking Network Documentation for the Modern Era” for a deeper dive on the benefits of adopting a new approach to network documentation.