Network Documentation: What You Need Before Something Breaks

Network problems are uniquely bad to troubleshoot without documentation. The symptoms are indirect. The cause is often invisible. And the pressure to fix it is immediate.

The time to document your network is not during an outage. It's before one, when you can think clearly and verify what you're writing down.

Here's what to capture.

The basics that most environments skip

IP addressing scheme. Your subnet structure, what range is allocated to what, and what's reserved. This sounds obvious but many environments grew organically without a plan, and nobody ever wrote down the logic behind the addressing. When you add a new site or VLAN, you're guessing whether you'll create a conflict.

VLAN structure. VLAN IDs, names, and what traffic belongs to each. If you don't have a diagram showing which VLANs are trunked to which switches, you're going to waste time when a device suddenly can't reach something it used to reach.

Gateway and DNS. For every subnet: default gateway, primary and secondary DNS servers. This belongs somewhere obvious, not buried in the router config.

DHCP scopes. What ranges are dynamic, what's excluded, what's static by reservation, and what's statically assigned outside DHCP entirely. The static-outside-DHCP devices are the ones that cause IP conflicts nobody can explain.

What a useful network diagram covers

A diagram that covers connectivity is more useful than a diagram that covers every device. You don't need every workstation on the diagram. You need:

• Core switching and routing: how sites connect to each other and to the internet
• Firewall placement and what's behind what
• Which VLANs exist and how they're segmented
• Server locations relative to the network
• WAN connectivity: ISP, circuit type, bandwidth

Keep it at the right level of abstraction. A diagram that tries to show everything becomes unreadable and stops getting maintained. A diagram that shows topology stays current and usable.

Firewall documentation

This is the documentation that's most often missing and most often needed.

Document your firewall rules with context, not just settings. A rule that says "allow TCP 443 from any to 10.0.1.50" is less useful than one that also says "web server for client portal, opened 2023-03-12, requested by ops team."

Rules accumulate. Rules that nobody remembers adding create security problems and troubleshooting confusion. The rule that seems unnecessary probably isn't, but without context you can't know.

Also document: NAT rules, VPN configurations (tunnels, client access), and any application-layer inspection policies.

Remote access

How do you get in when you're not on-site? Document every method:

• VPN: client software version, gateway address, authentication method
• Remote desktop / jump host: addresses, credentials location
• Out-of-band access: IPMI, iDRAC, iLO addresses for servers; console server for network equipment
• Vendor remote access: any persistent remote access tools installed by vendors, and for whom

Out-of-band access is particularly important. If the network is broken in a way that normal remote access can't reach, what's your fallback? If the answer is "drive to the site," document that too, including who has keys and physical access.

ISP and circuit information

For each internet connection:

• ISP name and account number
• Support phone number (the one that gets you to someone, not the general line)
• Circuit ID
• Type and bandwidth
• IP addressing: static IPs assigned, subnet, gateway, DNS servers from ISP
• Modem or CPE: make, model, management IP if applicable

This information is almost impossible to find quickly during an outage. The ISP account number is in an email from three years ago. The support number is different from the billing number. The circuit ID is on a label on the back of the router.

Write it down when things are working.

What to do with all of this

The format matters less than the accessibility. Documentation that lives in a place nobody knows about or can't access during an outage isn't useful.

A few practical constraints:

The documentation needs to be accessible when the network is down. A wiki that requires the corporate network to reach is not accessible when the corporate network is the problem. Keep a local copy somewhere, or use a cloud-based tool that's reachable from outside.

It needs to be current. A network diagram from two years ago is worse than no diagram if you trust it as accurate. Every time you make a change, update the documentation before you close the ticket.

It needs to be findable. The right person finding it in thirty seconds is more valuable than a comprehensive document that takes fifteen minutes to locate.

Start with what you'd need most urgently if something went down tonight. Build from there.