A Runbook is not a Checklist

It's a whole lot more...

A runbook is more than a simple checklist. A good one will be as useful to an expert as someone working through it for the first time. The key is for each step to have a "title" and a "description", and to carefully write each of them for a different audience. 

Titles serve the expert as a quick reminder of what comes next, while the description tells the novice (and sometimes even the expert) the details necessary to get it right. Good titles are:

  • commands written as a complete sentence

  • carefully balanced between brevity and clarity

  • not burdened with details of what is to be done or why

  • written assuming you already know what to do

On the other hand, descriptions are, in many ways, the opposite. While the same rules for any good writing still apply (clear, correct, and direct), good descriptions include:

  • a complete description of what is to be done, suitable for a newcomer to read for the first time

  • a discussion of the nuances, unusual circumstances, or other subtleties involved with that step

  • rich formatting (e.g., paragraphs, bulleted lists, images, etc.) as needed to make the step clear

The problem is that generic document tools make creating this distinction hard by requiring lots of tedious manual formatting to get everything in place. Even worse, authors need to repeat all this work with each document they touch.

Unfortunately, most dedicated checklist tools are even worse: only offering a single text field with around 200 characters for each step. This is both too short and too long. It's too too short because one often needs whole paragraphs worth of details, explanations, and nuance to explain the step completely. It's too long in that it allows mini novels to be written for each step, which are hard to parse quickly and accurately, and are far more than is needed to jog the memory of an expert.

Our product, Runbooks, provides a clear distinction between titles and descriptions by design. It even coaches runbook authors on writing short, clear titles for experts and richly formatted descriptions (including images and hyperlinks) for novices. Using Runbooks your team can't help but write better docs.