Ask any operations team about documentation and you’ll get the same answer: we know, it’s bad, it’s on the list.
I ran a 24/7 team across three data centres, and we had a knowledge base with hundreds of articles in it. It was still faster to phone one particular engineer at 3am than to search it. That’s the actual state of most knowledge management — not missing, just useless.
The reason isn’t laziness. It’s that documentation gets written at the wrong time, by the wrong person, for the wrong reader.
Written by whoever knows least
The person who understands a system best is the worst person to document it. They can’t see their own assumptions. They write “restart the service” because to them that’s one obvious action, and they’ve forgotten about the flag you need on a Tuesday, and the second node, and the thing you check first or you’ll corrupt a queue.
The best runbooks I’ve had were written by the person who was on call last week and struggled. They still remember which step was ambiguous, because it cost them twenty minutes at 3am. Write it while it still hurts.
The test is execution, not review
Most documentation gets reviewed. Someone senior reads it and says it looks fine. That proves nothing — they already know how to do it.
The only test that means anything: hand it to someone who has never done the task, and watch them do it without helping. Every time they hesitate, that’s a defect. Fix it then and there.
It takes twenty minutes and it’s the difference between a runbook and a document.
What actually belongs in one
I keep the format boring on purpose:
- When to use this. The symptom, in the words the alert or the user will use — not the words the system uses. People search for what they’re seeing.
- What you need first. Access, credentials, approvals. Nothing worse than getting to step 6 and discovering you need a permission that takes a day.
- The steps. Numbered, one action each, with the exact command. Not “restart the service” — the command.
- How you know it worked. A specific check. Otherwise everyone stops at the last step and hopes.
- When to stop and escalate. The most-skipped section, and the one that prevents a small incident becoming a big one. Give people explicit permission to stop.
Retire aggressively
A knowledge base is judged by its worst article, not its best.
If searching returns four articles and two are wrong, people stop searching — and they’re right to. One accurate article beats five where you have to work out which is current.
So delete things. Put a review date on anything load-bearing, and when it lapses, either someone re-validates it or it goes. That feels destructive the first time and it’s the only way the thing stays trustworthy.
The goal isn’t a big knowledge base. It’s that the person on call at 3am doesn’t have to phone anyone.