Runbook: written for the person woken at three in the morning

A runbook is a step-by-step procedure for a specific, known operational task: what to do when this alert fires, how to fail over that database, how to rotate these credentials. It is deliberately narrower than a playbook, which handles a situation requiring judgement — a runbook exists precisely where judgement should not be needed.

Its quality is measured by one test: can somebody who does not know the system follow it successfully, at night, without asking anyone. That is not a stylistic preference. Runbooks exist because the person on call is frequently not the person who built the thing, and the value of the document is entirely in closing that gap.

What a usable runbook contains

• The trigger — the alert, symptom or scheduled event this applies to, named exactly as it appears in the tool that will page someone.
• What the system does and what breaks when it fails, in two sentences. Enough orientation to act, not a design document.
• Prerequisites: access, credentials, VPN, tooling — checked before the steps begin, because discovering missing access at step four is where minutes are lost.
• Numbered steps with the exact commands or clicks, and the expected output after each. Steps without expected output leave the reader unsure whether it worked.
• Decision points stated explicitly: if you see this, go here; if you see that, escalate.
• How to verify the problem is resolved, not merely that the command ran.
• How to roll back.
• Escalation: who to contact, by what route, and after how long.

The commonest defect is assumed context

Runbooks are written by the engineer who knows the system, and they encode that knowledge invisibly: an unexplained abbreviation, a step that says "restart the service" without saying which host or which service, an implicit assumption about which environment you are in. Each one is trivial to the author and a dead end at 3am. The cheapest fix is to have somebody else execute the runbook once, in a drill, and to fix everything they had to ask about.

A runbook that has not been executed since it was written is a hypothesis. Systems drift, tooling changes, hostnames move. Attach a last-verified date, and treat anything older than a couple of quarters as unverified rather than current.

Link it to the alert

The runbook that cannot be found does not exist. Every alert that pages a human should carry a link to the procedure for it, in the alert itself, so nobody searches a wiki while a service is down. That requirement also produces a useful audit: alerts with no runbook are either not worth paging for or represent a gap, and reviewing that list periodically improves both the documentation and the alerting.

Where runbooks live

• Findable from the alert, not only from a documentation index.
• Version-controlled, so a change is visible and revertible.
• Owned by a named team, with a review cadence.
• Available when the system is down — a runbook hosted only on the platform it describes has an obvious failure mode.

Keeping them current

Ettex Docs holds runbooks with version history and the last-verified date visible, Ettex Records keeps the drill results and the review dates per procedure, and the step that turns a repeated manual procedure into a script is covered in runbook automation. What follows an incident is covered in incident postmortem.

Being direct: this is documents and records, not an incident management platform. Alert routing, on-call scheduling and automated execution belong in purpose-built tooling; what this covers is the content of the procedure, which no platform writes for you.