What is a runbook?

What is a runbook? It’s an IT phrase you hear thrown around a lot these days and everyone assumes you know what one is. I actually wrote runbooks at a couple of different points in my career without knowing that’s what I was doing. So it’s OK if you don’t know what one is. I’ll explain it.

What a runbook is

what is a runbook?
What is a runbook? Runbooks often take the form of decision trees, or include a combination of decision trees and step-by-step procedures to help you run a computer system.

A runbook is a collection of documented procedures and operations that explain how to run a computer system. Typically it contains procedures to start, stop, debug and supervise a system. Parts of the runbook may take the form of a decision tree, directing different instructions for different conditions the system administrator is seeing.

The goal of a runbook is to allow other operators or system administrators, with prerequisite experience, to operate a system effectively. The key is prerequisite experience. I’ve seen runbooks with troubleshooting steps like “turn on the monitor.” That kind of advice slows down a good system administrator and contributes to a toxic culture. Runbooks are no substitute for hiring people who know how to troubleshoot.

A good IT shop hires good people and gives them the tools they need. Runbooks are one of those tools.

Runbooks can exist as actual printed books, or in electronic form. They are easier to read in printed form, but electronic form offers some advantages. Being able to copy commands from the documentation and paste them into a command prompt reduces errors. Storing runbooks in a system that permits search also makes it easier to find the appropriate section quickly. It saves having to flip through a long table of contents or, worse yet, through the entire document.

Writing clearly

The key to writing runbooks is having sufficient detail and logical flow. I’ve seen runbooks that refer you to other documents and not put the steps in a logical order.

My runbooks were always very simple, unless someone dictated some other style. If this is happening, do these items in order. In the form of a numbered list. It eliminates the question of what happens in what order.

That form of writing doesn’t win literary awards. But it serves its purpose. It gets the important content in front of the reader in compact form, without fluff.

A more complex runbook should include a decision tree that refers the system administrator to the correct part of the document to handle the situation that’s happening.

What is a runbook in terms of automation?

Automation tools are all the rage in IT right now. These tools use something called runbooks. They are exactly the same idea as a runbook for a human, but they describe conditions and instructions for the computer’s automation tool to follow through. This lets computers take over some of the more repetitive work from human workers, freeing them up for work better suited to a human being.

The idea with these products is to make automation nearly as easy as writing documentation, while giving more capability than an average scripting language. Scripting is great but it usually won’t click a mouse for you.

The existence of these automation tools also reduces the need to hire “any idiot.” Typically you hire low-skill workers to do grunt work. The automated solution doesn’t get bored or tired or distracted. It’s also more consistent.

An in-between approach

Several times in my career, I’ve written a runbook and then realized most or all of it could be automated in simple scripting languages. When part of my runbook couldn’t be automated, I simply made the script pause, ask the human to do something, then hit a key.

My scripting is OK, not great. This approach increased speed and efficiency and consistency. All of those were good things.

My style of breaking a process down into logical, ordered, and brief steps, outlined above, encourages this. Often the simple steps plug neatly into a script. My runbook was, effectively, a type of pseudocode.

If you found this post informative or helpful, please share it!