A runbook template that works at 3am (for every brain)

Runbooks written as paragraphs fail everyone during an incident, and fail dyslexic engineers hardest. This template is the distilled version of what several practitioners in this community converged on independently.

The template

# Runbook: <service> - <failure scenario>

## System picture
[One diagram. What talks to what. Where this procedure acts.]

## When to use this
- Symptom: ...
- Alert(s): ...
- Do NOT use if: ...

## Steps
1. One action only.
   `command --in --a --block`
2. What you should see before continuing:
   `expected output`
3. Next single action.

## You are done when
- [ ] Check X returns Y
- [ ] Alert Z has cleared

## If this didn't work
Escalate to: <team/rota>. Say: "<one-line summary>".

The rules that make it work

• One action per numbered step. "Restart the service and check the logs" is two steps. Splitting them is what makes the list followable when adrenaline is high and eyes skip lines.
• Every command in a code block. Copy-paste beats transcription for accuracy - for everyone, at any hour.
• Expected output after any step that can surprise you. Half of runbook failure is "is this normal?"
• Explicit done-state. A checklist, not a feeling.
• The escalation line includes what to say. Composing a coherent summary mid-incident is a reading/writing task at the worst possible moment. Pre-write it.

Why diagram-first matters

Text describes a system one word at a time; a diagram shows it all at once. For visual-spatial thinkers (heavily represented in infrastructure), the diagram is the documentation and the text is the appendix. Even a rough box-and-arrow picture beats three paragraphs.

Draw it once in draw.io/Excalidraw, export PNG, embed at the top. Update it when the system changes - an outdated diagram is worse than none.