Design Guide
A runbook is only as good as the worst moment someone has to use it.
Most runbooks are written by the person who least needs them. This guide is about writing for everyone else: the colleague covering your week off, the client's IT person, or you in a year, at an hour when nobody is thinking clearly.
01 · Before you write
Answer four questions first.
Most of a runbook's quality is decided before the first step is written. If you cannot answer these in a sentence each, the procedure is not ready to be written down yet.
What exactly does it do?
Name the system and the outcome. "Export the archive mailbox for a departing user on Contoso's tenant" beats "Mailbox procedure".
When is it used, and when not?
The trigger: a ticket type, an alert, a date. Say just as clearly when it is the wrong runbook, and which one to use instead.
Who will follow it?
An engineer, a help-desk tech who rarely opens a shell, or someone on call at 3 a.m. Write for the least experienced likely operator. If the operators really differ, write two runbooks.
How do we know it worked?
Decide the success check before the steps. If you cannot describe what "done" looks like, neither can the operator.
Drafting with an AI tool?
Put your answers to these four questions in the prompt. That's what turns a generic draft into your procedure.
02 · Anatomy
The parts of a good runbook, in the order the operator needs them.
Hand-written runbooks tend to have the steps and little else. The parts they skip are the ones that matter when something goes wrong: what access you need, when to stop, and how to tell it worked.
-
1
Purpose, scope and compatibility
One or two sentences: what this does, to which system, and what it leaves alone. Plus the systems and versions it was written and tested for, so nobody runs a Server 2019 procedure on Server 2012.
-
2
When to use it
The trigger, and the cases where it does not apply.
-
3
What you need before you start
Roles, permissions, modules, tools, network access, a maintenance window, who to tell. Listed up front, so nobody finds out at step 7 that they lack the admin role step 8 needs. This is the single most valuable part to get right.
-
4
Settings
Every value that changes from one run to the next, set once at the top: names, paths, addresses, limits. Never secrets.
-
5
Checks that change nothing
Confirm you are connected to the right place and the starting state is what you expect, before anything is touched.
-
6
The numbered steps
One action each, with what to expect and when to stop.
-
7
Verification and success criteria
Prove it worked with a check, not a feeling. Then record the result: what, when, who.
-
8
Abort conditions
The exact signs that mean stop, written where the operator will be when they appear, and who to call.
-
9
Rollback
How to put things back, ending with a check that the rollback itself worked. A runbook that changes something without a way back is half a runbook.
The same parts, laid out in a plain-text runbook
Put rollback in its own runbook
Tacked onto the end, it gets skipped when things go well and missed when they don't. Make it a runbook of its own, and name it up front.
03 · Writing steps
Eight habits of a step that works the first time.
04 · Side by side
The same step, written twice.
Weak
- Which server, and how much is "enough"?
- No command, so everyone checks differently.
- "The usual folder" lives in one person's head.
- Two actions in one step, with no stop point between them.
- Nothing says what success looks like.
Good
Get-PSDrive -Name $export_drive
- Says it is safe, so nobody hesitates to run it.
- The drive and the limit come from Settings, so they are the same everywhere in the runbook.
- Says exactly where to look and what number matters.
- The stop point and who to tell are in the step itself.
- The export is the next step, not the same one.
05 · Common mistakes
Where good procedures still go wrong.
Prerequisites found the hard way
Seven steps in, the operator discovers they lack the role step eight needs, and the system is now half changed.
Written only for the author
Shorthand, skipped "obvious" steps, and context that only exists in one head. Fine for the author, useless for the operator.
No way back
No abort conditions, no rollback, no check that a rollback worked. Everything is fine until the one run where it is not.
Placeholders treated as real
Example names, flags and paths, copied from a template or an AI draft and never checked against the actual environment.
Never tested by anyone else
An untested runbook only records what its author believes the procedure is.
Quietly out of date
The system changed, the runbook did not, and there is no version or date to warn the operator.
06 · Testing and upkeep
A runbook is finished when someone else has followed it.
Test it
- 1Run it once, end to end, on a test system or a non-production copy.
- 2Have someone who did not write it follow it while you watch and say nothing.
- 3Every place they hesitate, ask, or scroll back is a step to rewrite.
- 4Test the rollback runbook too. It is the one you will need least often and most urgently.
Keep it current
- ✓Version every change. A date-based version such as 261008.1 tells the operator how old it is at a glance.
- ✓Say what it is compatible with. Name the systems and versions it was tested on in the Compatible with: line, and update it when you test on something new.
- ✓Name an owner. The "Prepared by" line is who to ask, and who updates it.
- ✓Fix it after every run. Anything that surprised the operator goes back into the text before it is forgotten.
- ✓Review it when the system changes, not on a calendar alone: upgrades, new modules, renamed servers.
- ✓Publish with a hash. Send the file's SHA-256 by a different route from the file, so the operator can confirm nobody changed it on the way.
07 · Before you hand it over
The checklist.
Good habits, enforced where it counts.
Thinware Runbook Builder turns your plain-text runbook into an interactive runbook that keeps steps in order and puts settings in fields. Writing it well is still up to you.