Every district has documentation. It lives in a wiki nobody updates, a folder of screenshots, and the head of the person who built the network. The question is not whether you have it, but whether it survives a week of your absence.
This is the standard I would hold a district wiki to, and the structure that makes it achievable.
Write for the 02:00 reader
That reader is tired, has no context, and cannot ask you a question. They need:
- What this thing is and what breaks if it stops.
- How to tell whether it is healthy, from a client — not from the server.
- The exact commands or menu path, with the expected output.
- What to do if the first thing does not work.
- Who to call, and when.
Anything that fails that test is a note, not documentation.
Four kinds of page
| Type | Answers | Example |
|---|---|---|
| Overview | What is this and why does it exist? | "Network Infrastructure" |
| Design | How is it built, and why this way? | VLAN and subnet plan |
| Procedure | How do I do the thing? | Add a VLAN, restore a backup |
| Reference | What are the values? | IP table, port list, vendor contacts |
Most wikis are 90% reference and 0% design, which is why they explain what the addresses are but not why the network is shaped that way.
The structure that survives
Book
└── Chapter
└── Page
├── Purpose (one paragraph)
├── Overview (how it fits)
├── Procedure (numbered, with expected results)
├── Verification (how you know it worked)
├── Rollback (how you undo it)
└── Related (links, not duplicates)
A page without verification and rollback is a suggestion.
Never publish a credential
Document where the credential lives — "Proton Pass → UniFi controller" — not the value. A wiki is backed up, exported, and occasionally shared; a password in it is a password in all of those places.
Write procedures as state, not clicks
"Click Settings, then Routing, then Static Routes" ages badly: menus move, vendors rename things. Write the intent first, then the path as a hint:
Goal: route 10.50.0.0/16 to the new campus via 10.0.0.10.
1. Add a static route: destination 10.50.0.0/16, next hop 10.0.0.10, distance 1.
2. Verify: the route appears in the table and a sourced ping from a district host succeeds.
3. Rollback: delete the route; traffic falls back to the default.
The goal survives a UI redesign. The clicks do not.
Keep it alive
| Practice | Why |
|---|---|
| "Last updated" on every page | Stale pages are worse than missing ones |
| Named owner per book | Someone is responsible for accuracy |
| Review after every incident | The incident found the gap; fix it while it is fresh |
| Docs in the same repo as config | Changes and documentation move together |
| Link, do not copy | Duplicated tables drift |
The most effective habit is small: when a change takes longer than expected because the documentation was wrong, fix the page in the same session. That is how a wiki stays true without a documentation project.
Worked example: an outage runbook
A page for "Internet down at a campus":
- Purpose — restore internet access; the campus has no local breakout.
- Verify — from a staff device:
ping 10.0.0.1, thennslookup example.com, then a browser. - Diagnose in order — fiber status, gateway WAN IP, default route present, DNS resolution, firewall policy hits.
- Common causes — fiber cut (call circuit vendor, ticket number), route missing after a change (compare to the documented table), DNS forwarder loop (test against the resolver directly).
- Escalate — circuit vendor, then the ISP account rep, with the circuit ID.
- Rollback — if a change caused it, restore the previous configuration backup.
That page is worth more than a hundred pages of inventory, because it is the one someone opens when nothing works.
What breaks in production
- Screenshots without text. The UI changed; the screenshot is now misinformation.
- No owner. Everyone assumes someone else updates it.
- Reference without design. You know the VLAN IDs, not why the network is shaped that way.
- Secrets in the wiki. Once published, always published.
- Documentation in one person's head, which is not documentation.
Checklist
- Every page states its purpose in the first paragraph.
- Procedures include verification and rollback.
- Each book has a named owner and a last-updated date.
- Credentials are referenced by location, never by value.
- The top ten incidents each have a runbook page.
- Documentation changes ship with the configuration change they describe.
Next
Documentation describes the network. Continue with Read-Only API Auditing to verify it against reality.