A runbook has to survive a 3 a.m. read, by someone who is not the person who wrote it and does not have time to guess.
Runbook — payment queue backlog
The queue holds over ten thousand messages and the consumer-lag alarm has fired twice in an hour. Start at step one even if the cause looks obvious.
If the backlog has not fallen below two thousand messages thirty minutes after step four, page the payments lead and open an incident.
An incident runbook only works if whoever is following it at the worst possible hour can trust that what's in front of them is current, and can copy a command without retyping it by hand. A step that might go wrong needs to say so before it is attempted, not after. Whoever is on call needs this to hold up, not whoever is deciding whether to buy the software that hosts it.
A command that stays a command, not a sentence about one
A step that needs an exact command keeps its own formatting and can be copied whole, so a tired hand is not retyping a line that a paragraph quietly reworded.
A warning set beside the step, not folded into it
What could go wrong is marked in its own colour immediately above the step it applies to, rather than folded into the same paragraph as the instruction, so it isn't the kind of line a fast skim quietly slides past.
A history you can open, and restore, not just check
While a team edits together, a version is cut automatically every thirty minutes and the last thirty are kept; open one to see a step as it stood at the time, and restore it if the current version has it wrong. Writing alone, a version is kept on every save instead.
Which step people get stuck on
You see which step, by its own heading, keeps someone there longest, and whether they double back to it after moving on to the next one — often the sign that one instruction needs rewriting before the next incident.
An example — not your document. Sections are the document’s own headings.
Most of their attention went to “Note” — 2m 18s of 4m 00s. They came back to “Note”.
Time each section spent on screen, counted only while the tab was in front and the reader was active. It shows what was in front of them, not what they read.
This page is about what a runbook has to do. For the blocks the editor is built from — see the editor.
Yes — the history keeps up to thirty versions; open one to see it as it was, and restore it if you need to. While a team is editing together a version is cut every thirty minutes rather than on every save; writing alone, one is kept each time you save.
No — nothing in the document enforces that. It's a visual signal, not a gate against skipping ahead; whether it gets noticed before someone acts is still on them.
Not yet — begin with a blank document; the numbered steps, the warnings, and code that keeps its own formatting all work from the first line.