How to Write an IT Runbook That People Actually Use

A runbook is supposed to answer one question: how do I do this thing correctly, right now, when I don't have time to figure it out from scratch?

Most runbooks fail that test. They're either so high-level they leave out the steps that actually matter, or so detailed that maintaining them becomes a job in itself and they go stale within six months.

Here's how to write one that works.

What a runbook is for

A runbook is a step-by-step procedure for a task that happens more than once. Its purpose is to make that task repeatable without requiring the person who originally did it to be in the room.

The test is simple: hand the runbook to someone who is competent but has never done this specific task. Can they complete it successfully? If yes, it's a good runbook. If they have to call you twice, it needs work.

Common tasks that benefit from runbooks:

• New server provisioning
• User onboarding and offboarding
• Backup verification
• Patch management
• Incident response procedures
• Certificate renewals
• Site failover

Anything you do more than twice a year, and anything that would cause a problem if done wrong, is a runbook candidate.

The structure that works

A good runbook has six sections. You don't always need all six, but you should decide deliberately when to leave one out.

Purpose and scope

One or two sentences. What does this runbook cover and when is it used? This sounds obvious but it matters when you have thirty runbooks and someone is trying to find the right one quickly.

Example: "This runbook covers the process for provisioning a new Windows Server in the production environment. Use this for physical and virtual servers. For Azure VM provisioning, see the cloud runbook."

Prerequisites

What needs to be true before you start? Access requirements, tools that need to be installed, approvals needed, other tasks that need to complete first.

This is the section most runbooks skip, and it's the source of most runbook failures. Someone follows the steps correctly and hits a wall at step 4 because they don't have the access they need.

Steps

Numbered. Specific. In the order they happen.

The common mistake is writing steps at too high a level. "Configure the firewall rules" is not a step. The steps are: log into the firewall, navigate to this menu, create a rule with these settings, verify the rule is applied.

Include expected outputs for steps where something is supposed to happen. "You should see a confirmation message" or "the service should show as running in the services panel." This lets someone know they're on track without having to call you.

Verification

How do you know it worked? This is separate from the steps because it sometimes requires a different access level or a time delay. A clear verification step prevents the "I think it worked" outcome where you discover the problem two weeks later.

Rollback

If something goes wrong, how do you undo this? This section is optional for simple tasks and mandatory for anything that touches production.

Write this section when you write the runbook, not when something has already gone wrong. When things are broken, you don't have time to figure out rollback steps from scratch.

Contacts

Who do you call if this goes sideways in a way the runbook doesn't cover? Vendor support numbers, internal escalation paths, who owns this system.

Common mistakes

Too much assumed knowledge. The person using the runbook in an emergency may not be the person who wrote it. Write for someone who knows IT but doesn't know this specific system.

No version history. Runbooks go stale. When you update one, note what changed and when. A runbook that was accurate eighteen months ago and hasn't been touched since may or may not be accurate now.

Combining multiple procedures. One runbook, one procedure. If you're writing a runbook for "server maintenance" that covers patching, backup verification, and disk cleanup, split it into three. Shorter runbooks are easier to follow and easier to update.

Not testing it. Before a runbook is "done," have someone who wasn't involved in writing it follow it. They will find the missing steps you assumed were obvious.

Keeping runbooks current

A runbook that's out of date is a liability. It gives you confidence you shouldn't have.

The only practical system: whenever you do a procedure, follow the runbook and update it as you go. If a step has changed, fix it before you close the ticket. If the runbook was missing something you had to figure out, add it.

Treat the runbook as the source of truth. If you found yourself doing something that isn't in the runbook, either the runbook needs updating or you did something wrong.

That discipline, applied consistently, keeps documentation current without a separate documentation project. The update happens during the work, not after.