What good network documentation actually contains

Why documentation decays

Documentation is usually produced once, at the end of a project, and then left alone. Every change after that — a new VLAN, a replaced switch, a firewall exception — moves the real network a little further from the drawings.

After a year or two, people stop trusting the diagrams and start logging into devices to find out what is true. At that point the documentation has become a liability: it costs time to maintain and gives wrong answers when it matters.

The minimum useful set

If you only keep a few things current, keep these:

Logical diagram

Sites, routing domains, VLANs or VRFs, firewalls and the paths between them. One page per site plus one for the WAN is usually enough.

Physical diagram

Rack elevations and which port connects to what, especially uplinks, circuits and anything without redundancy.

IP address plan

Every subnet, its purpose, gateway and DHCP scope, in one place rather than spread across devices.

Configuration history

Automatic, versioned backups of every device, so you can see what changed and roll it back.

Circuit register

Carrier, circuit ID, bandwidth, contract end date and the support number for every link.

Runbooks

Written steps for the incidents you see most: a circuit down, a switch failure, a firewall failover.

Make it part of the change, not a project

The habit that keeps documentation alive is simple: a change isn’t finished until the documentation reflects it. Put a documentation check in the change template, and make it part of peer review.

Automate what you can. Configuration backups, inventory and even some diagrams can be generated from the devices themselves. Humans should spend their time on the parts tools can’t infer — intent, ownership and the reasons behind design decisions.

Store it where the team already works

Documentation in a personal drive or an engineer’s laptop disappears when that person moves on. Keep it in a shared, access-controlled location with version history, and make sure credentials are held in a proper password vault, never in the diagrams.