Tallwatch
Back to blog
2 min read
On-callGuide

How to write a runbook a tired engineer will actually open

A runbook that reads like a wiki homepage fails at 2am. Write the three steps that unblock the incident — then stop.

NK

Nabin Khair

Founder

How to write a runbook a tired engineer will actually open

Nobody reads a runbook at noon for fun. They open it when the pager has already ruined the night. If the first screen is a philosophy of the service mesh, they will close it and start guessing.

What belongs on page one

  1. How you know this is the incident — the alert name, the symptom, the dashboard or monitor link.
  2. Immediate checks — three to seven commands or clicks, copy-pasteable.
  3. Mitigations that buy time — rollback, feature flag, scale up, failover.
  4. When to escalate — and to whom.
  5. Where logs and graphs actually are — deep links, not "see observability platform."

Everything else — architecture history, old outages, owner trivia — goes below a fold or in a different doc.

Tone

Write like a text to a teammate:

  • "Check if the last deploy was in the last hour: ___"
  • "If error rate > 5% on login, disable ___ flag"
  • "Do not restart the primary DB without ___ in the loop"

Avoid:

  • "It is important to consider…"
  • Undated screenshots of a UI that shipped two redesigns ago
  • Commands that only work on your laptop

Length

One screen for the common path. A second section for "still broken." If you need a novel, you need smaller alerts — each page should map to a play, not to the whole product.

Keep them alive

After an incident, spend ten minutes on the runbook before the postmortem polish. Add the command that actually worked. Delete the step that wasted twenty minutes. Stale runbooks are worse than none because they create false confidence.

The gate

No runbook, no page. Put the link in the alert body. On-call should not hunt Confluence while customers wait.

Pair this with when to page vs notify and a real escalation policy. Tools route the person; the runbook tells them what to do when they arrive.

Related

Keep reading

False alerts and status pages.

Cheaper PagerDuty alternatives for small teams (2026 pricing)

Cheaper PagerDuty alternatives for small teams (2026 pricing)

What on-call actually costs a team of 5 or 10 on PagerDuty and nine alternatives, using November 2026 list prices, plus what you give up when you pay less.

NKNabin Khair
Opsgenie end of life: dates, options, and what to do now

Opsgenie end of life: dates, options, and what to do now

Opsgenie support ends on April 5, 2027. What Atlassian recommends, why one of its two migration paths is itself being phased out, and a month-by-month plan to switch before the deadline.

NKNabin Khair
Opsgenie alternatives in 2026: free plans and migration help

Opsgenie alternatives in 2026: free plans and migration help

Opsgenie support ends April 5, 2027. Compare 10 replacements by free plan, starting price, and Opsgenie import tools, with honest picks for small teams.

NKNabin Khair