Runbook

A runbook is written for a person who did not build the system, is under time pressure, and has a symptom rather than a diagnosis. Every useful convention follows from that reader.

The most common structural mistake is organising it like the system: one section per service, describing what each does. That ordering requires the reader to already know which component is at fault, which is most of the problem. Organise by failure mode instead, with headings that read like the report you will receive: “the nightly report did not arrive”, “customers report 401 errors”, “the retry queue is growing”.

Each entry needs six parts:

1. Symptom, including the literal error text, because that is what people search for.
2. Confirm, one command or dashboard link that proves this is the right section.
3. Likely causes, ordered by how often they actually occur, not alphabetically.
4. Fix, as exact copy-pasteable commands rather than descriptions. “Restart the worker” assumes knowledge; the literal invocation does not.
5. Verify, from the outside. A green log line is not verification; the order appearing in the warehouse system is.
6. Escalation, with a name and a channel, and what to record before escalating.

Above the failure modes, a short block that rarely changes: where it runs, where the logs are, which credentials it uses, who owns it, what is safe to restart, and what breaks if it is down for an hour.

What does not belong: architecture diagrams, design rationale, and copied API reference material that will go stale.

Test it by handing it to somebody who did not build the system, breaking something in staging, and saying nothing while they work. Every pause is a missing assumption, every question is a missing line, and every tab they open is a link the document should have contained.

A runbook that only its author can follow is a draft. See also observability, which supplies the signals the runbook tells people to check.