Network Documentation Best Practices: What to Create & Why

Everybody agrees network documentation is extremely important, but there tends not to be a lot of agreement on what that documentation should include. The short answer is that it should include everything that’s relevant—but what that means varies between networks.

For example, in a really small network with one switch and a firewall, and perhaps a single wireless access point, there isn’t much to document. It might be enough to put everything in a single diagram. But in a bigger network, you need to follow the general principle that somebody else will need to support this thing one day and you want to be remembered positively.

Network documentation must-haves

So the actual documents you need will vary depending on the network, but the following table shows the relative importance of a typical network.

Importance	Document	Type	Notes
Critical	Layer 1 or Layer 1 / 2	Diagram	Should show key infrastructure
Critical	Layer 3	Diagram	Should show key infrastructure
Critical	Circuit numbers	Table	Sometimes this is done within a trouble ticketing system
Critical	IP Address allocation	Table	This could be a tool rather than a spreadsheet to allow easy sharing
Useful	Rack layout	Diagram	Particularly for data center
Useful	WiFi layout	Diagram	Depending on how important the WiFi is
Useful	Cable plan	Diagram	Particularly useful if the drops are not numbered the same as the desk locations
Useful	Routing protocol	Diagram	Becomes critical if you run a routing protocol of any complexity
Useful	Security view	Diagram	This is more useful for explaining your security than for troubleshooting
Useful	Cloud services	Diagram	Becomes critical if you run a cloud of any complexity
Useful	Patching table	Table	Particularly useful during implementation
Useful	Asset tracking	Table	Particularly infrastructure assets and support contracts
Useful	Password vault	Table	Should be encrypted
Nice to have	Detailed design document	Document	Becomes critical in larger environments with lots of support staff
Nice to have	Support document	Document	Depends on the support organization
Nice to have	Routing and spanning tree snapshots	Document	Useful for troubleshooting

Critical network documentation

Layer 1 and 2 diagram

A Layer 1 diagram shows the physical connections between the critical pieces of network infrastructure. It includes things like link speeds and cabling types. I like to see individual port numbers or designations on a Layer 1 diagram. Normally I represent the faster links using thicker lines and I use different colors for fiber and copper as well as for storage and data networks.

I often combine Layer 2 features onto the Layer 1 diagram because they seem to go naturally together. Layer 2 features include things like VLAN numbers, link aggregation, and trunk connections. Also, any Layer 2 diagram must include spanning tree information such as the root bridge and any bridge and link priorities that have been changed from their defaults.

If you aren’t running a spanning tree, then you probably need a separate diagram to document what you’re doing with TRILL or alternatives thoroughly. And if you don’t have a spanning tree or TRILL and you have more than one switch, you’re doing it wrong.

Layer 3 diagram

Layer 3 diagrams include all your IP segments and all the network devices that interconnect them. That generally means Layer 3 switches, routers, and firewalls. The IP segments should indicate any relevant VLAN ID numbers and a brief one or two-word description of the intended function, as well as the IP network number and mask. I like to put the IP addresses of the network devices on this diagram as well.

Any important redundancy mechanisms like HSRP or VRRP should be clearly indicated on the Layer 3 diagram. However, I don’t put end devices like servers on a Layer 3 diagram unless they have some extremely important network function—for example, a DHCP, DNS, or LDAP server.

Those are the network diagrams you absolutely need to have. In addition, you should have diagrams that represent other important features of your network. What’s considered important will depend on the network.

Circuit number table

Another piece of critical documentation, particularly if you have any WAN circuits or voice circuits, is a detailed listing of all of your circuit numbers. The list should include the circuit numbers and the network provider, as well as any information about where the circuit goes.

If it’s an MPLS circuit, the spreadsheet should include all of the MPLS provisioning information. If it’s an Internet circuit, then the amount and detail of the information could vary wildly depending on the provider and the type of circuit. And if it’s a point-to-point circuit, then it makes sense to include information about what’s on the other end.

I like to include support information in this listing of circuit numbers. What phone number do I call if this circuit goes down? If I need to provide special support contract information when I make that call, it should also be recorded here.

IP address allocation table

Next is the IP address allocation spreadsheet or database, which should include every internal and external, registered and private, IPv4 and IPv6 address you have in your environment. Every subnet should be listed separately, and every individual device should be recorded. If you’re using DHCP, which is also a good practice, for a range of addresses, just indicate these are dynamic addresses. But every static address allocation should be recorded.

Also, and this is most important, you need to be able to reserve addresses that you intend to use for a particular purpose in the future. Otherwise, you’ll inevitably wind up giving out the same addresses to two different projects and creating completely avoidable conflicts.

I like to have a separate spreadsheet for all of my NAT addresses in which I describe exactly what each address is used for. If I have multiple internal or DMZ devices mapped to a single external address on different ports, then I carefully record each NAT rule. This makes life much easier the next time you need to add a new NAT rule.

Useful network documentation

Rack layout diagram

A rack layout diagram shows the server room or wiring closet racks with all of the equipment and patch panels. If you have equipment mounted to be accessible from both the front and back of the cabinet, then you should have diagrams for both the front and the back.

A rack layout diagram should be meticulously accurate about what equipment is mounted in which numerical position on the rack.

You’ll use a rack layout diagram when planning for where to put that next piece of equipment, as well as when talking to technicians and other IT staff about where to find things. It’s extremely important when you’re telling somebody to shut off the power to a particular device that they get the right one.

Rack layouts can also specify things like which aisle is hot and which one is cold, as well as power distribution. However, I don’t recommend putting patch cords on a rack diagram. That information is likely to change regularly, and it only clutters up the picture without adding much useful information. I’ll talk about how to record patching information later.

Wi-Fi diagram

If you have an important Wi-Fi component to your network, that should be documented. For Wi-Fi, I like to see floor layouts showing the physical locations of all access points (APs), preferably with RF radiation patterns indicated. This is particularly important if there are any special antennas in use with non-symmetrical radiation patterns.

As well, a good Wi-Fi diagram shows all of the SSIDs along with their intended purposes and security mechanisms. And if there are central Wi-Fi controllers, this information should be indicated in a text box.

Cable plan

A similar diagram that comes in handy whenever you’re troubleshooting an office network problem (like finding the guy who created a loop by cleverly plugging two jacks into the same unauthorized workgroup switch) is a cable plan. This diagram allows you to map the usually inscrutable jack numbers to physical locations in your building.

Routing protocol diagram

Another useful diagram is a routing protocol design. If there are separate routing domains that don’t directly exchange routes with one another, I often make them separate diagrams. For example, if I have an internal OSPF or EIGRP routing domain and an external Internet BGP routing domain, I always make these separate diagrams.

The routing protocol diagram should indicate all autonomous systems, internal areas, and redistribution points and it should clearly indicate special features such as route tagging or filtering.

Security diagram

Another special-purpose network diagram I like to include in my documentation package is a security view. It’s similar to the Layer 3 diagram except that it focuses on things like the Internet edge, as well as any internal or Internet DMZs.

Of course, all special security equipment needs to be clearly indicated on this diagram.
The standard Layer 3 diagram includes firewalls, but the security diagram needs to also include any special security probes, IDS/IPS devices and passive or active taps. I also want to see central management devices like SIEMs and log servers on this diagram. If there are any important NAT rules or firewall rules, it’s often useful to indicate these as well.

Cloud services diagram

If you have any cloud services like AWS, you should document them. Cloud service diagrams need to include all of the security zones, and should probably also include all of the virtual servers in the environment.

If you have any special network security infrastructure in your cloud services like firewalls, load balancers, or WAF virtual devices, they need to be clearly described so that the next person can easily understand what you’ve done and how to manage it.

If you have a VPN between the cloud and your internal network, it’s extremely important to include that feature on the diagram because it’s here the most sensitive information will typically be sent, and it’s also a potential backdoor into your network.

Patching table

In a data center, you should document your patch panels. Data centers usually have many different kinds of links, from fiber and copper to perhaps some Twinax or Infiniband. And every device is both important and potentially unique. Mistakes could take down the entire network.

Conversely, the patch panels that support all of the users in the west wing of the third floor probably have most of those users connected to identically configured switch ports. It’s certainly useful to keep a good patch table for it, but it’s really not as critical as the data center patching information. As I mentioned earlier, though, you do want to have a physical map showing where all of those office cables go so you can troubleshoot problems down to the end user.

At a minimum, the patching documentation should show, for every port in the panel, exactly what’s connected on the other end of the cable. If the device or panel on the other end has lots of ports, then the destination port should be uniquely identified along with the device.

The documentation should also indicate what type of patch cord is used. Is it Category 6? Is it fiber? If it’s fiber, is it single mode or multi-mode, and what are the connector types on both ends? If the patch cords have unique identifying numbers, which is a good practice, those numbers should also be included.

Asset tracking

It’s very useful to have a table of asset tracking information. For this, I’m usually not too concerned about commodity items like phones, printers, or workstations. Instead, the list should include the critical pieces of infrastructure like switches, routers, and firewalls, as well as any critical pieces of server hardware.

In the asset tracking information table, I want to see manufacturer names, models, serial numbers, and license numbers. You also want to include support contract numbers so you know who to call if something goes wrong.

Password vault

One important and useful piece of documentation is a password vault. If you have static administrative passwords on any of your network appliances, store these credentials in an encrypted vault of some kind. In general, I prefer the devices to use a central authentication system like RADIUS or TACACS, but inevitably there will be some devices that need static passwords. And in most cases, you’ll also have fallback passwords that can be used if the central authentication system breaks.

Nice-to-have network documentation

Some other pieces of network documentation depend on the situation.

Network design document

If I’m designing a network for a client, I often do a detailed design document. It’s often a fairly long document in which I describe the design and explain the intended functions of every new feature and a new section in the network.

It can be helpful to include a decision log where you identify all of the key design decisions and explain why they were made. For example, perhaps you’ve chosen to use a particular routing protocol because of the need to support a particular legacy requirement. Or you might have wanted to implement a more sophisticated and robust feature in part of the network but ran into compatibility problems so you had to resort to a brute-force solution instead. These notes become very useful later when you wonder why something was done a particular way and whether it’s safe to change it.

Network support document

I sometimes write a support document to help with migrating the infrastructure to production. It includes things like suggestions for how to implement new systems within the framework that I’ve made and recommendations for where and how to modify security restrictions to allow new services through the firewalls without compromising the design. It might also include troubleshooting notes. For example, I might list the expected symptoms of common failure modes like circuit failures.

Routing snapshot

If you run a particularly large network, it’s often useful to maintain a good set of routing snapshots of the routing tables for use when troubleshooting. This could include routing protocol information as well. And you could similarly record other dynamic topology information like spanning tree link states for the same reason.

Final thoughts

Now that I’ve outlined what to collect and document, there’s still the question of how you will do it—that’s your documentation process. Tools can help you automate the process so you’re not spending all your time manually collecting and maintaining information. They can also ensure that all members of your team always have the same accurate information.

But no matter what method you use, what’s important is a consistent process that produces quality information and keeps that information up to date.