The runbook someone else can operate

A runbook is the artefact that decides whether a deployment outlives the person who built it. Most are written at the end, by the person leaving, from memory, and they describe the system that was designed rather than the one that runs. The fix is to write it in week two, when the surprises are fresh, and to test it on someone who was not there.

Nine sections

1. What this is, in three sentences. What it does, who uses it, and what happens to their work if it stops. No architecture yet.

2. The happy path. One numbered sequence from trigger to output, with the actual command or screen at each step. If a step has two possible paths, one of them is the exception path and belongs in section 5.

3. Where everything lives. Accounts, repositories, dashboards, the customer's system names, the secret store. Named accounts, not "the team's account" — a shared login is an unowned risk.

4. The numbers to watch and their normal range. Three to five metrics, each with a range that means healthy. A dashboard without expected values teaches nobody what abnormal looks like.

5. Failure modes and the first move for each. The five to ten things that have actually gone wrong, with the detection signal and the first action. This section is the reason the document exists; the rest is orientation.

6. How to turn it off. The exact steps, tested, with the time it takes and who may authorise it. Include the reverse — how to turn it back on — because a rollback that nobody has practised is a hope.

7. Data: what is stored where, for how long, and how it is deleted. Required in any deployment touching personal data, and requested in audits far more often than teams expect.

8. Known debt. The three things everyone knows are fragile, why they were left, and what would trigger fixing them. A runbook with an empty debt list is a runbook nobody trusts.

9. Who to call, and for what. Named people, with the escalation thresholds, matching the escalation path.

The test that proves it

Hand sections 2, 5 and 6 to someone who has never touched the system, with a real task: take a record through the happy path, diagnose one seeded failure, and turn the feature off and back on. Sit silent while they do it.

Three outcomes. They finish, and the document is real. They get stuck at a step that assumed knowledge, and you fix the step. They ask you a question, and you write down the question — because the question is the gap.

Run this before the handover meeting, not after. A runbook tested in the meeting is a document being edited in front of the person who has to rely on it.

The failure modes of runbooks

Written to impress. Architecture diagrams, design rationale, a paragraph on why Kafka was chosen. The reader needs none of it at 2am, and its presence pushes the operational content later.

Written from the design, not the system. The runbook describes three services; production runs four, and the fourth was added in week six to fix a timeout. Anything not verified against the running system is fiction.

No ownership after handover. A document with no named maintainer decays from the day it is written. One name and a review date at the top is enough; it converts a file into a commitment.

The verbal supplement. "And I'll be around if anything comes up." This is the most common failure and the most damaging, because it means the handover did not happen — the FDE moved to another customer and remains the de facto operator, unpaid.

Where it sits in the exit

The runbook is the main deliverable of the handover discussed in the sunset clause, and its section 5 is fed by the incident reviews of the deployment it describes. A deployment whose runbook was written in week two costs a day to hand over; one written in the last week costs a month and still leaks.

The question to ask before writing it

Who, exactly, will open this file, and what will they be doing when they open it? If the answer is a named person with a named job, write for them and delete everything they do not need. If there is no such person, that is the finding: the deployment has no owner on the customer side, and no document fixes that. It is the same gap named in the stakeholder map.