Blog · Runbooks as conversation scripts, not encyclopaedias

Darren Goh · 2025-01-18

Runbooks as conversation scripts, not encyclopaedias

Hero for Runbooks as conversation scripts, not encyclopaedias
Runbooks balloon when every author adds every fact they know. Instead, treat each page as a script with three beats: detect, stabilise, communicate. Detection lists the fastest signals that confirm the issue is real. Stabilisation lists the smallest reversible change that buys breathing room. Communication lists who needs what first. Paragraph two should capture dependencies without nesting five levels of bullets. If a dependency needs its own novel, link out and keep the main path thin. Thin paths survive midnight adrenaline; nested trees do not. Third paragraph belongs to verification. After each stabilisation step, what should improve, where should we look, and how long should we wait before trying the next lever? Explicit waits prevent stacked changes that confuse rollback. Close with maintenance hygiene: who reviews the runbook after each related incident, how you prune unused steps, and how new hires rehearse it during onboarding dry runs.

Tags: runbooks, operations, training

All field notes