what a runbook is
the codebase tells you how the system was built. the runbook tells you how to live with it. every project we ship ends with one — a single markdown document in the repo, indexed, that answers the questions you will have at 2am on a thursday when something is on fire and the person who built it is asleep.
it is the part of the deliverable that does not show up in a demo. it is also the part that decides whether you own the system or rent it.
what is in it
five sections, in order.
deploy — the exact commands to push code to production, with rollback.
secrets — what credentials exist, where they live, who has access, how to rotate them.
on-call — which alerts page someone, what each one means, and the first three things to check for each.
debug — how to read the logs, where the traces live, which dashboards matter.
architecture decisions — a short adr per major choice. why postgres and not mongo, why ecs and not kubernetes, why rest and not graphql. one paragraph each, written when the decision was made.
plain language. diagrams earn their space. every command is paste-able. every link works.
when we write it
as we build, not at the end. an adr happens the day a decision lands. a deploy step is documented the week the pipeline is set up. by the time we reach handover, the runbook is most of the way written — handover week is for review, gaps, and one full read-through with your team.
we also run a real on-call drill in handover week. someone on your team triggers a fake alert, follows the runbook end-to-end, and finds the gaps. we close them before we leave.
why it earns its space
thirty days after we hand the project over, we are still on call for questions at no extra cost. about 80% of those questions are answered by the runbook before we read them — the team checked first, the answer was there, the question never got sent. that is the metric we care about. the runbook is the thing that makes the engagement actually end.
the codebase ages with the team that maintains it. the runbook is how that team stays the maintainer with confidence.