What documentation should a well-run network have, and how do you keep it current?
Show the answer
Say this first
Physical and logical diagrams, an IPAM with every subnet and allocation, a device inventory with software versions and support contracts, configs backed up with history, circuit details and carrier contacts, standards and templates, runbooks, design decisions with their reasons, and a change log. It stays current only if updating it is part of closing every change, and best of all if diagrams and configs are generated from a source of truth instead of drawn by hand.
Go deeper
| Document | Contents | Used when |
|---|---|---|
| Physical diagram | Racks, cabling, patch panels, fiber paths | Site visits, cabling changes, outages |
| Logical diagram | VLANs, subnets, routing domains, VRFs, firewalls | Troubleshooting, design reviews |
| IPAM | Every block, subnet and reservation | Any addressing change |
| Inventory | Model, serial, software, support contract, end of life | Upgrades, renewals, RMA |
| Config backups | Versioned configs with diffs | Rollback, audits, after a failure |
| Circuits | Carrier, circuit ID, SLA, contacts, escalation | Every WAN outage |
| Standards | Naming, templates, port and VLAN conventions | Every new build |
| Runbooks and MOPs | Steps for routine work and known failures | Changes and on-call |
| Design decisions | What was chosen and why | When someone asks "why is it like this?" |
Keeping it alive
- Make documentation updates a closing step of every change, checked in review.
- Use a source of truth (NetBox or similar) for devices, IPs, cables and circuits, and generate diagrams and configs from it where you can.
- Back up configs automatically with a tool that keeps history.
- Keep an offline copy reachable during an outage. Docs on a server behind the broken network do not help.
Traps
- Saying "the configs are the documentation". Configs show what, never why.
How did you do?