Runbooks

A runbook is read by someone tired, stressed, and possibly unfamiliar with the system. That is the only design constraint that matters, and it rules out most of what people write.

Write for the least-experienced person who could be paged, not for yourself. If it only works because the reader already knows the system, it is notes, not a runbook.

The test: could someone who has never touched this service follow it without waking you?

1. Start from the alert, not the system

One runbook per alert or symptom, named the way the reader encounters it. A page fires with a name — that name must lead straight to the document.

Not "Payment Service Documentation" but "PaymentQueueDepthHigh". The reader is not browsing.

Link it from the alert itself. A runbook nobody can find during an incident does not exist.