A runbook template for technical tasks

A runbook is a set of instructions for a task you may need to repeat. When you are tired or working through an incident, it helps to have the action, expected result and recovery steps together.

A starting template

Copy this and adapt it to one task. Replace placeholders with the commands and checks for your own system.

# Runbook: &lt;service> - &lt;failure scenario>

## System picture
[One diagram. What talks to what. Where this procedure acts.]

## When to use this
- Symptom: ...
- Alert(s): ...
- Do NOT use if: ...

## Steps
1. One action only.
   `command --in --a --block`
2. What you should see before continuing:
   `expected output`
3. Next single action.

## You are done when
- [ ] Check X returns Y
- [ ] Alert Z has cleared

## If this didn't work
Escalate to: &lt;team/rota>. Say: "&lt;one-line summary>".

Make it easy to follow

Give each step one action. Put the expected result directly underneath it, with an example where useful. Say when to stop and who to contact if the result is different.

Keep explanations close to the step they support. Put longer background reading at the end, so it does not interrupt someone trying to resolve a problem.

Try it before an incident

Ask someone who did not write the instructions to follow them in a safe test environment. Note where they pause or need information you left out. Add a last-tested date and update the runbook when the system changes.