Network documentation that survives contact with reality

Every organisation has documentation that was accurate on the day it was written. The usual response is a resolution to keep it updated, which fails for the same reason it failed before. A better response is to document differently.

Record what changes slowly

Some facts change constantly: current configurations, interface states, which port a device is on. Others change rarely: why this site has two uplinks, which VLAN is for what, which supplier to call, what depends on this server.

The slow-changing facts are also the ones you cannot recover by looking at a device. A configuration can be read from the router. The reason for a strange static route cannot. Document the reasons and let tools collect the current state.

Write for the person at 3am

The most valuable document is not a comprehensive reference. It is the page that tells someone half-awake what this system does, what depends on it, what normal looks like, and who to call. Short, specific, and current because it rarely needs to change.

Put it where the work happens

Documentation in a wiki nobody opens is not documentation. Interface descriptions live on the device and are read every time someone looks. Comments in a configuration are read by whoever edits it. A README beside a script is found by whoever runs it.

The closer the information sits to the thing it describes, the more likely it is to be both read and updated.

Diagram what is true

A diagram showing physical connectivity and address plan, at low detail, stays useful for years. One showing every port and every VLAN is wrong within a month. Draw the level of detail you are prepared to maintain.

Date everything

A document with a date can be assessed. Undated documentation is trusted until it causes an incident. “Last verified March 2026” tells the reader exactly how much weight to give it, and that honesty is worth more than an unverified claim of accuracy.