Skip to content

How to write a runbook

TL;DR

A good runbook lets any ElfVenger complete a task correctly without asking. Lead with a TL;DR, give numbered steps, flag the dangerous ones, and say how to tell it worked. Copy _page-template.md to start. This page is both the guide and the worked example.

The house style

  1. One page, one task. If it needs "meanwhile, also…", split it.
  2. TL;DR up top. Three sentences max — the answer for someone skimming under pressure.
  3. Numbered steps for procedures. Each step is one action. No buried sub-steps.
  4. Flag the risky bits. Use admonitions by severity:
    • !!! danger — irreversible, billing, or account-affecting actions.
    • !!! warning — easy-to-miss gotchas.
    • !!! note / !!! info — asides and context.
  5. Say how to verify success. "You'll know it worked when…".
  6. No secrets. Point at where a credential lives (e.g. the 1Password item), never paste the value.

Worked example: structure of a runbook

# Reset a customer's app password

!!! abstract "TL;DR"
    Do X in the admin panel, confirm Y, tell the customer Z.

## Before you start
- What access you need
- What information to gather from the ticket

## Steps
1. First action.
2. Second action.
   !!! warning "Watch out"
       The thing people get wrong here.
3. Third action.

## Verify it worked
- The signal that confirms success.

## If it goes wrong
- Common failure → what to do / who to escalate to.

Gotchas / watch out for

  • Don't link to external systems with relative markdown links — the rendered site can't resolve them, and the build's link-check will fail. Use the system's name or an absolute URL instead. Relative .md links are only for pages inside this repo.
  • Keep volatile values out of prose where you can — prices, plan names, and limits change. Point at the source of truth instead of copying it.