Ownsteps

Ownsteps / Guides

IT runbook template: how to write one someone can follow during an outage

Reviewed .

A runbook is the page you open when something is already wrong: the VPN is down, a mailbox is full, a backup job failed. The reader is stressed, may not know the system well, and has no time for background. Most runbooks fail because they were written for the author, who already knew what the steps meant.

This guide gives a runbook template you can copy, a worked example, and a short review test. It works with a text editor and manual screenshots.

Runbook, SOP or checklist?

An SOP describes a task that is done the same way every time. A checklist is a list of things to confirm. A runbook responds to a situation: it starts from a symptom or alert, helps the reader decide what is going on, and ends with either a fix or a clear handoff to someone else. If your document begins "to do X, follow these steps", it is an SOP; see the free SOP template. If it begins "when you see X", it is a runbook.

Runbook template

RUNBOOK: [short name of the problem]
Owner: [role]    Last tested: [date]    Applies to: [system / client / version]

1. TRIGGER
- What you see (alert text, user report, error message)
- How to confirm it is this problem and not a look-alike

2. IMPACT
- Who or what is affected
- How urgent it is (and what changes the urgency)

3. BEFORE YOU START
- Access you need (role names, not passwords)
- Anything you must not do first (restart, delete, change a setting)

4. STEPS
1. [Action] -> [what you should see]
2. [Action] -> [what you should see]
(If the result differs, go to STOP CONDITIONS)

5. STOP CONDITIONS
- If [x] happens, stop and escalate to [role / how]
- If steps 2-3 do not fix it within [time], escalate

6. ROLLBACK
- How to undo what you changed

7. CONFIRM IT IS FIXED
- The check that proves it, and who to tell

8. AFTERWARDS
- What to record in the ticket
- What to improve in this runbook

Two parts do most of the work. The expected result after each step tells the reader whether to continue. The stop conditions keep a worried person from trying a fourth fix that makes things worse.

Example: a user cannot sign in to the shared mailbox

A structure example. Replace the system names with your own.

  1. Trigger: A user reports "access denied" opening the shared support mailbox. Confirm it is this problem: other mailboxes open normally for the same user.
  2. Impact: Support cannot read customer mail. Urgent if the mailbox has no other active member.
  3. Before you start: You need the mail admin role. Do not remove and re-add the mailbox; that loses the saved rules.
  4. Steps: Open the mail admin console and find the mailbox. Check that it is not marked disabled. Open Members and look for the user; you should see them listed with Full access. If missing, add them and wait ten minutes. Ask the user to sign out, then back in.
  5. Stop conditions: If the mailbox is missing from the console, stop and escalate to the mail owner. If the user is listed with access and still cannot open it after sign-out, stop; do not recreate the permission more than once.
  6. Rollback: Remove the member you added if the request turns out to be unauthorised.
  7. Confirm: The user opens the mailbox and sees mail from today. Note the cause in the ticket.

Write for the worst moment

Test it before you need it

Ask someone who did not write the runbook to follow it in a test environment or against a harmless case, with the author watching silently. Every question is a missing sentence. Write the answer where the question came up, then record the date in "Last tested". A runbook that has never been followed by a second person is a draft.

Adding screenshots for browser steps

Many runbook steps are clicks in a web console. A screenshot of the exact screen, with the right button visible, answers questions words cannot. You can capture them manually. Ownsteps is a Chrome extension that records webpage clicks, takes a screenshot at each, and builds an editable step-by-step guide on your computer; you can edit titles, delete detours, black out private areas and export Word, PDF, HTML or Markdown. It does not capture desktop applications, terminals or remote sessions, so steps outside the browser need manual notes. Check each screenshot for customer names, tokens in the URL and notifications before sharing; see the redaction checklist.

Keep it findable and current

Store runbooks where the on-call person already looks, named by symptom ("Shared mailbox access denied"), not by system. Give each an owner and a review date, and update it after every incident where it fell short. For client-specific differences, see IT documentation for MSPs; for filled-in procedures, SOP examples.

Review checklist