Networking
Network documentation that works: the minimum artifact set
The network documentation that gets used and stays current: L3 diagrams, IPAM, patch records, change logs, and the docs-as-code workflow that keeps them alive.
Executive summary
Network documentation is the set of artifacts that lets an engineer who has never seen your network operate it safely: an L3 diagram, an IP address plan, physical/patch records, device configs under version control, and a change log. Most documentation fails because it tries to capture everything and therefore captures nothing current. This article defines the minimum artifact set worth maintaining, what to deliberately not document, and the docs-as-code workflow that keeps the set honest.
The test your documentation has to pass
Here is the only test that matters: an engineer who has never touched your network gets paged at 3 a.m. for a site outage. Can they, from documentation alone, work out how traffic is supposed to flow, what changed recently, and which cable to trace? If yes, you have documentation. If they need to call the one person who “knows the network,” you have a bus-factor problem with a wiki attached.
I have operated networks as a one-person provider and inherited them on enterprise accounts, and the failure mode is identical at every scale: documentation efforts die of ambition. Someone declares that everything will be documented, builds a forty-page template, fills it in once, and the network changes out from under it within a quarter.
Stale documentation is worse than none.
None sends the on-call engineer to the network itself, which at least tells the truth. Stale documentation gets trusted, and trust in wrong data extends outages.
The fix is to maintain the smallest set of artifacts that passes the 3 a.m. test, and to bind their maintenance to the change process so they cannot drift.
The minimum artifact set
1. The layer-3 diagram
One diagram per routing domain showing subnets, VLANs/segments, routing boundaries, firewalls, and WAN/Internet edges. Not the physical topology, not every switch — the logical map of where packets can go and what they must cross to get there.
Rules that keep it useful:
- Every subnet on the diagram carries its CIDR and its purpose, not just a name.
- Firewalls and ACL enforcement points are visually distinct — this diagram doubles as the security zone map during design reviews and incidents.
- One page per domain. If it needs a plotter to print, it needs splitting.
2. IPAM as the source of truth
A spreadsheet is a valid IPAM at small scale; NetBox-class tooling earns its keep somewhere around a few hundred prefixes. What matters is not the tool but the rule: an address that is not in IPAM does not exist. Allocation happens in IPAM first, configuration second. The moment engineers hand out addresses from memory and backfill “later,” the database becomes an archive of past intentions.
Record per prefix: CIDR, VLAN/segment, site, purpose, gateway, and the routing domain it belongs to. Record per static assignment: address, device, interface, and owner.
3. Physical and patch documentation
Rack elevations and patch records are boring exactly until a failed line card forces someone to trace cables in a hot aisle. Label both ends of every cable, keep the patch record with the rack elevation, and photograph racks after major work — a photo with a date beats an unmaintained Visio of the same rack every time.
4. Configurations under version control
Every device config belongs in a Git repository, pulled automatically (Oxidized, RANCID, or your NCM of choice). This is the artifact that answers the most valuable operational question there is: what changed? A config diff timestamped an hour before the outage began is a finished troubleshooting session. It is also your recovery path when hardware dies — see the troubleshooting methodology for how config diffs collapse the search space.
5. The change log
A chronological record of what changed, when, by whom, and why — even if “change management” in your organization is a Slack message. The discipline of writing one line per change is cheap; reconstructing the last month of changes during an incident is not.
What not to document
Deliberate omissions keep the set maintainable:
| Don’t document | Because |
|---|---|
| Per-port switch maps for access ports | Generated on demand from the switch; stale in a week |
| Full running configs in prose | The repo has the config; prose copies drift |
| Vendor defaults | Document deviations from default, not the manual |
| Step-by-step GUI procedures | They rot with every firmware release; document intent and CLI |
The pattern: document intent and relationships, generate state from the network itself when needed.
Docs-as-code: how the set stays alive
The only documentation that stays current is documentation maintained inside the change workflow. The practice I hold teams to — and it maps directly to the IaC operating model:
- Diagrams live as text where possible (Mermaid, draw.io XML committed to the repo) next to the configs they describe.
- A change is not reviewable unless the pull request touches the documentation the change invalidates. Reviewers reject config changes that leave the diagram or IPAM stale — same standard as code changes without tests.
- Quarterly, one engineer runs the 3 a.m. test for real: pick a site, hand the docs to whoever knows it least, have them narrate how they’d diagnose a failure. The gaps they hit are the next quarter’s documentation backlog.
Implementation notes
- Starting from zero: build the L3 diagram first, IPAM second. Those two artifacts pay for themselves within the first incident.
- Inheriting an undocumented network: generate before you draw. CDP/LLDP walks, routing tables, and ARP data will reconstruct 80% of the truth; interviews fill the rest. Draw what is, not what the last architect intended.
- Keep secrets out of the documentation repo — configs go in sanitized (SNMP communities, keys, and password hashes stripped or vaulted), per standard security review practice.
Documentation is not a deliverable; it is an operating capability with a maintenance cost. Budget for the smallest set that passes the 3 a.m. test, bind it to the change process, and let everything else be generated. Tools and diagram formats will keep changing. The test does not.
Frequently asked questions
- What network documentation is actually essential?
- Five artifacts: a layer-3 diagram showing subnets and routing boundaries, an IPAM (IP address management) source of truth, physical rack and patch documentation, device configurations in version control, and a change log. Everything else is optional; these five let a stranger operate the network safely.
- How do you keep network documentation up to date?
- Make documentation part of the change itself, not a follow-up task. If the diagram and IPAM edits ship in the same pull request as the config change, documentation stays current by construction. Anything maintained on a separate schedule from the change process will drift within months.
- Is a CMDB the same thing as network documentation?
- No. A CMDB is an inventory of things; documentation explains how the things fit together and why. Networks have failed audits with a perfect CMDB and no usable L3 diagram. You need the relationships and intent, not just the asset list.