When working with runbooks, you can easily find yourself with one which is too big to be practical. Perhaps the initial process was just bigger than you expected, or it had many more details to cover than you realized. It also happens that runbooks can grow over time as new or missing steps are added. Eventually, the runbook becomes unwieldy, and people either have difficulty with it or just stop using it altogether. At this point, it's time to break it up into pieces. This guide will walk you through the process.

Finding the Seams

It's easiest to start breaking down a runbook by looking for individual steps which are full runbooks in themselves. Look for any step that:

• is occasionally performed by itself

• has a bulleted or numbered list enumerating a bunch of "sub-steps"

• has clear bookends which could form a clear runbook by itself

• is performed by someone different from the person/group who performs the rest of the runbook

If any of these are true, that step is a candidate to become its own runbook. 

The second thing to look for is groups of steps which could logically be a new runbook. In addition to the criteria above, consider:

• Is there a clear set of bookends all the steps share?

• Is there some person, place, or piece of equipment common to all of those steps?

• Are all the steps usually performed at the same time, with a gap before and/or after?

If so, then you may have found a good candidate for a new runbook.

Extracting the Pieces

Once you have found a step (or steps) you want to extract, pull up a clean sheet and start a new runbook. From there, the process is similar to starting a runbook from scratch in some ways, but since you already have some initial content there are a bunch of differences. Start by refreshing your memory on the bookends you chose, and then revise the content you copied over. Here are a few things to look for:

1. Evaluate bulleted/numbered lists to see if they are really sequences of instructions (rather than a list of materials, for example). These should be converted into actual steps in the new runbook.

2. If you started with multiple steps from the original runbook, consider whether those are still the right steps. The division of work which made sense in the original runbook may no longer make sense in your new runbook.

3. Consider whether there are any "missing" steps a novice would need to successfully complete the runbook. These often go missing when a detailed process gets crammed into a single step.

4. Fill out details on each step which "didn't fit" into the original runbook. For example, this often happens when you convert a bulleted list into actual steps. Try to ensure each step has a similar level of detail.

Now, go back to the original runbook, and replace the original step(s) with a single new step which refers to the new runbook you just created (if you're using our Runbooks app, you can just add a link). Re-read the original runbook with the new step in place, taking the time to read new runbook in its proper place in the sequence. You particularly want to be sure nothing got lost in between the two runbooks. Use the bookends you selected for your new runbook to decide where any missing pieces actually belong.

Of course, now you just need to go back and repeat the same process for each candidate you identified!

Our website, Runbooks, eliminates a lot of friction in this process. Just pop open two windows, and you can easily refer back and forth to move over the original content. Then, when you're finished, it's easy to link to your new runbook from the original so they stay connected as they should be.

This release features a completely re-imagined dashboard screen. Instead of a simple list of runbooks & runlogs, the new dashboard shows what each team member is working on, who is waiting on whom, and how far along each runlog in the system has gotten.

— Andrew Miner

Release Notes

Features Added

• all new dashboard showing a much more complete view of who is working on what runlogs

Nuisances Remedied

• revised all fonts to be easier to read

Bugs Fixed

• none

Operations Improved

• none

A runbook is a description of how to change the world from some starting point to some desired goal. But, it can be hard to figure out what does and doesn't belong in that runbook if you're vague about what the boundaries are. Choosing definite bookends for each runbook can be a huge help.

For example, you might have a "Set up a new employee's laptop" as one of your business's runbooks. There are a lot of things which have to be true before you'd want to do that, and it has to end with the laptop actually ready to be used. But, there are also a lot of somewhat related things that are also part of getting a new employee ready which may or may not be part of that runbook. How do you know which to include? The bookends for the runbook will tell you.

An ideal set of bookends has a number of common traits:

• they each represent a single moment in time

• it is unambiguous and obvious when they have happened

• they define a natural starting and stopping point for the overall job

• they are clearly related to one another and to the job being performed

Choosing the Starting Bookend

The easiest way to find the actual starting point of a runbook is to pick a step you're sure is somewhere in the middle, and then ask yourself: "What do I need to do first?" Keep repeating that question until you drill down to the very first step. Now, ask: "How do I know when it's time to do that?". That's your starting bookend.

Let's consider the example of hiring a new employee. Perhaps you are the co-owner of a seasonal tour guide business. You hire people on for the summer, with the understanding that the job ends in the fall. So, if you have a runbook to hire someone, when does it really start?

Maybe the first thing that occurs to you is that you need to put an ad in the local paper. Is that the very first step? No... you need to decide what you're paying for the position first. Is that the first step? No... you need to chat with your partner to decide on your overall staffing plan first. Is that the first step? Yes. That's when you do your thinking for the season and make all the relevant decisions. So, how do you know when it's time to schedule that meeting? It's always on May 1st. Therefore, that date is the starting bookend.

Choosing the Ending Bookend

Choosing the ending bookend is superficially just the reverse of choosing the starting bookend. Keep asking: "Is this the last step?" until you answer "Yes". The real difficulty is deciding when to stop this process. After all, it's easy to endlessly keep adding more and more to the runbook since there's always more to do.

A better approach is to ask yourself: "What is the logical goal of this runbook?", and then: "What observable event tells me that goal is clearly and finally finished?". Considering our earlier example of hiring summer help, the logical goal of the process is to get people to agree to show up and give tours. So, the observable, unambiguous, and final event which marks the ending bookend is when the signed employment contract is filed with the company's official papers. Anything after that point no longer serves the goal of hiring, but rather on-boarding the new employee.

Bookends as Handoffs Between Runbooks

Often, the ending bookend for one runbook is the starting bookend for another. You can picture this like a number line. In reality, there are just a lot of individual tasks which are all connected to one another. The bookend is the spot on the number line where you divide one runbook from the next:

So, instead of a single runbook, you may be writing a set of related runbooks, and the question of bookends is really: where do you divide one runbook from the next? In general, it's often best to break where:

• all the steps after some one step are conditional upon that step

• the person responsible for the overall job changes

• there's a natural delay from one step to the next

• there's clearly a new goal involved

Let's re-consider our first example: setting up a laptop for a new employee. Naturally, you wouldn't do this before they accept the offer! In fact, you wouldn't want to start until you were sure everything was completely finalized: in other words, not until the "Hire a new employee" runbook was finished. The ending bookend for that runbook is the perfect starting bookend for the next:

• no step of setting up the laptop should start until the employee has accepted

• the hiring manager performs the first runbook, while an IT support person does the second

• the employee may not start for a few weeks, and the laptop set-up need only be started a week beforehand

• hiring a new employee is clearly a separate goal from setting up a laptop

Our product, Runbooks allows you to easily include the bookends for your runbooks in their descriptions. The description can even link to the runbook(s) which may follow or precede it so the sequence from one to the next is always clear.

As with any good writing, one of the most important things in writing a good runbook is to figure out: who is it for? In the case of a runbook, this is the same as answering: "Who is going to do the work in this runbook?" The problem with writing a runbook is that they are frequently used by multiple people with wildly different needs. So, how do you answer the question?

Keep a Specific Person in Mind

The easiest way to keep the proper perspective in mind is to pick a few people who represent the different audiences for your runbook. In fact, think of specific individuals whom you know well, and whom you've worked with for a little while. That way, it will be easier to put yourself inside their head while you're writing your runbook.

The Old-Timer

Generally, you can include yourself as an example of an expert who is also familiar with your business. However, you have to assume you're writing for your future self who's been away from this task for few weeks or months, and needs a bit of reminding. As you're writing the titles for each step, ask yourself: "What would my future self need to remember how to do this?" Your future self will, of course, not require a lot of detailed hand-holding. You just need a set of crisp, short instructions to jog your memory.

The New Guy

The second person you want to think of is the most recent experienced person to join your team. They are generally experienced in their field, but they don't know your systems yet. When writing the descriptions of each step, try to recall what you did and didn't need to tell this person when getting them started. What do you already know is unique to your business? What seemed surprising to them which they hadn't seen elsewhere? What tools or software had they not used before? On the other hand, what was already obvious to them? All of these will help you decide both what to include and what not to include.

The Novice

A third person you might want to include in your mental audience is the last person you hired with no background at all (e.g., an intern or new grad). What terms, acronyms, or concepts tripped them up? What questions did they have which your "experienced" hire didn't ask? On the other hand, what kinds of things seemed to be general knowledge they already had? You may not want to actually spell all this out in your runbook—it is meant to be a working document: not a tutorial—but you might want to include links to other materials to help novices figure things out.

The Special Cases

Between these three people, you're usually pretty well covered. However, if your runbook involves working with computers (or some other specialized skill), you might include both someone who's very good with computers, and someone else who is bad with them. Or, if your runbook involves different people handling different steps, you will want to include an example of each. If you know this task got botched in the past, think of the person responsible, and try to figure out what you could include which would have prevented the problem.

Our product, Runbooks, is specifically designed to make this approach to perspective-taking as easy as possible. Not only does each step allow a separate title and description, but they all live online in a shared location, so it's easy to actually ask your different audience members for feedback.

As always, I love to hear your feedback on how Runbooks is working for you, and what you would like to see added in future releases!

— Andrew Miner

Release Notes

Features Added

• users have the option to sign up from the login page if they enter an unknown email address

Nuisances Remedied

• the "assigned to you" section of the Dashboard only shows one step from each runlog

• subscribers to the Runbooks blog no longer get duplicate release notes emails

• missing padding on runlog step previews while editing

• extra long markdown elements (e.g., tables, links, code blocks, etc.) now scroll horizontally if needed

Bugs Fixed

• pressing "enter" with an incomplete email address no longer attempts to login

• due dates are displayed on completed runlog steps

Operations Improved

• none

We've also spent some time fine-tuning the new user experience so all new accounts will receive a bunch of sample runbooks which explain how to use the website.  Naturally, we've also squashed a bunch of the most urgently annoying nuisances you've reported.

As always, I love to hear your feedback on how Runbooks is working for you, and what you would like to see added in future releases!

— Andrew Miner

Release Notes

Features Added

• Runbooks is now mostly‡ compatible with mobile devices as small as the iPhone 8.

• All steps in a runlog you own as assumed to be assigned to you and will be displayed as part of your dashboard.

• Sample runbooks are automatically added to new accounts.

Nuisances Remedied

• Images with a white background no longer render strangely in runbooks/logs.

• The default title of a new runlog is now the combination of the runbook's title and today's date.

Bugs Fixed

• Completed steps can no longer be edited.

Operations Improved

• The debug screen copied to the clipboard when opening an issue now includes the User Agent.

‡ There are still a few features which aren't available on mobile. These all have to do with editing the actual text of a runbook or runlog. For these functions, you'll still need a tablet, laptop, or desktop computer.

You've finally decided your team really needs to start writing down how they do different things. Maybe someone left the team, and there was a frantic rush to transfer knowledge. Maybe you've gotten fed up with having one too many costly mistakes in some complicated process. Whatever the reason, you're determined that things are going to be different next time, and that means writing things down. But, where do you start?

For describing step-by-step processes, there's nothing quite so ideal as a runbook. They are a kind of checklist which provides clear, precise instructions for experts while simultaneously providing all the details needed by a novice (see: A Runbook Is Not a Checklist for more details). Before you can start writing one, though, you need to decide which processes are worth the time and effort.

8 Criteria for Making a Runbook

I use these 8 criteria for deciding whether it's worth writing a runbook for a process:

• complexity — easy ➔ hard

• risk — low ➔ high

• urgency — planned ➔ sudden

• experience — expert ➔ novice

• frequency — often ➔ seldom

• duration — brief ➔ extended

• participants — one ➔ several

• observers — none ➔ many

Let me walk through each of these in turn.

1. Complexity: Hard

This is the obvious one. If a process is long and complicated, chances are very good that you're going to miss something important unless you're following some kind of guide. However, just because something is fairly simple doesn't mean it won't benefit from a runbook. The following criteria outline cases where it may be worthwhile to create a runbook for even a simple process.

2. Risk: High

This one, too, is pretty obvious. When there's a good chance of something bad happening, we naturally try to be careful, slow down, and double-check ourselves as we go along. An excellent way to do that is to write down each step we're going to take ahead of time, review it, and then rehearse it. Writing a runbook makes it easy to do all of those things.

3. Urgency: Sudden

We all tend to panic a bit in an emergency. Processes which are usually simple become daunting, and we have a greater tendency to make mistakes. In these situations, it's immensely helpful to have a clear list of steps to follow right in front of us. It's even easier if those steps are a clear and well-written runbook with all the necessary details right at hand.

4. Experience: Novice

Many businesses have tasks which usually fall to the newly hired, newly graduated, or simply inexperienced. These folks need a disproportionate amount of help with any given task, and one can't assume they already know all the details. It takes a huge burden off the rest of the team to have detailed runbooks for these folks.

5. Frequency: Seldom

Paradoxically, it's often those processes which you perform infrequently which benefit the most from having a runbook. The simple reason is just that we forget things: especially those things we don't do very often. So, when considering a process you only do quarterly (or worse, annually), it's much more likely to benefit from a runbook.

When you have the right tools...

These first five criteria will help you identify good candidates for runbooks, even if you're just using pen and paper. Processes which meet the next three criteria get an extra boost when you're using our product, Runbooks. It has lots of features which make your runbooks way more powerful than a ball-point pen.

So, on to those last three criteria...

6. Duration: Extended

The longer a process takes to finish, the more likely you are to step away to do something else. Of course, when you return to it, you find yourself asking: "Where was I again?". Having a written process makes it much easier to pick up where you left off. Even better, Runbooks automatically keeps track of where you were so you have a written record of what you have and haven't finished. You can even take notes right in the log, so you never lose track of the details.

7. Participants: Several

The more people involved in a process, the more communication is needed to ensure that: 1) everyone knows what they have to do, and 2) when it's their turn to do it. Having a clear, written record of the process is great for clarifying the first point, but it won't help you with the second. Runbooks is great for both since it lets each step be assigned to different team member, and will automatically inform the next assigned person when it's their turn.

8. Observers: Many

Some processes are higher profile than others. But, when there are a bunch of people who want to know what's going on, life can quickly degenerate into an unending flood of requests for "status". Having a written runbook helps because you can simply tell people what step you are on. Even better is not having to do that yourself. Runbooks allows any number of people to sign up for notifications, and control the granularity themselves.

Examples

So far, this has all been fairly abstract. Let's consider some specific examples to help make these concepts more concrete. I've drawn some (anonymous) examples from actual runbooks people have made using our product.

Giving a Tour

Consider a small co-working space. Every week or two a potential customer gets in touch to take a tour before deciding whether to rent a spot. The tour itself includes walking around the entire space, pointing out various useful features, giving a few nominal gifts (e.g., a coffee mug), and answering questions. If the person says they definitely want to rent a spot, the tour also includes pointing out how to operate various pieces of equipment (e.g., the coffee maker, projectors in the meeting rooms, door locks, etc.). The tour is usually given by the community manager, who is a fairly recent hire, but the owners of the space want to know when tours are given.

How does this process rate? Using our eight criteria, this process deserves a runbook because it has: high complexity, moderate experience on the part of the community manager, and several observers.

Pre-Flight Checklist

Imagine you're the pilot of a small aircraft, and you're about to take a friend on a pleasure flight. You've done this many times before, and you have no particular reason for special concern. Nevertheless, you pull out a pre-flight checklist and thoroughly inspect many aspects of the aircraft and its performance before taking off.

How does this process rate? This is also is a good candidate for a runbook because it is moderately complex (such checklists usually have roughly two dozen items), and because the risk of missing something is so terribly high.

Responding to an Outage

We software engineers are frequently are called upon to respond to problems with the software we create: sometimes unexpectedly and in the middle of the night. The steps provide a sequence of things which might potentially have gone wrong, and instructions on how to verify that they are working correctly. Since outages rarely happen at convenient times, instructions need to be written for a groggy engineer who's been abruptly woken up to check things out. Moreover, since all the engineers on the team share being on call, they must be written so that the least experienced member of the team can use them.

How does this process rate? This is perhaps one of the most common cases for a runbook since it hits so many of our criteria: high complexity, high risk (of breaking things further), urgent, often several participants, and usually many observers.

Draining the Hot Tub for the Summer

Runbooks needn't always be for serious, work-related items. We have a runbook which outlines the steps to drain and service someone's hot tub. There are a number of bits to disassemble, and hoses must be connected to the correct places in the correct order to avoid floods. Plus, this is something one only does once a year, so the details are never fresh in mind when one goes to do it.

How does this process rate? In this case, the risk is moderate (flooding), but the real catch is that the frequency is very low (annual). That makes it very likely you'll have forgotten some important detail between occasions when you do this chore.

Most of the common tasks around your business probably don't need a runbook. They're simple, low-risk things which are performed often enough that qualified people have no problems doing them correctly. However, it's also probably true that there are quite a few processes which would benefit from a runbook because they're complex, high-risk, or one of the other eight criteria. Whatever the reasons, Runbooks is the perfect place to put them.

While most of our attention was on externally facing things, we added a few improvements within the product itself, too.  You can now add markdown descriptions to your runbooks & runlogs.  If you're a team admin, you can change your team's name.  And, finally, we also fixed a number of bugs and minor nuisances.

As always, I love to hear your feedback on how Runbooks is working for you, and what you would like to see added in future releases!

— Andrew Miner

Release Notes

Features Added

• The landing page now focuses on the value of Runbooks for small businesses

• Signup has been simplified to only require the user's email address

• Users now use email login links instead of passwords to log in

• Team admins can change the name of their team

• Runbook editors can add a markdown description of a runbook/runlog 

Nuisances Remedied

• Clicking on the Runbooks logo returns you to your own dashboard (instead of the public landing page)

• Revised the runbook & runlog icons to look more clearly like a book & clipboard, respectively

Bugs Fixed

• Record actual completed at time for each individual step (not just the last step)

• Fixed the error page when an unknown page is requested

• Fixed error when visiting with an expired session to simply return to the login page

Operations Improved

• Reduce event logging to only those which reflect user intent (i.e., not API calls)

• Update event reporting to call out which sections of the landing page have been viewed

Starting with a blank page can be daunting. Fortunately, when writing a runbook, you have a head start: the actual process you want to document. Chances are, you already know how to do that process rather well, and doing the same thing you always do is a great way to begin writing the runbook.

This guide describes multiple levels of refinement when writing a runbook. You can stop at any level and still have a useful product. In fact, it will probably make sense to stop at a different level for each runbook. That way, you can get the most value for the least amount of work.

Level 1: Take brief notes as you perform the process

Start by doing the process as you usually would the next time it comes up naturally. As you go along, take quick notes for yourself about each individual step you take. These notes are merely to jog your memory later on, and to ensure you don't miss anything important. Don't feel compelled to write so much that you distract yourself from the job at hand.

The result of this level is a partial set of ad-hoc bullet points outlining what you did this time around. It's fine if these don't make much sense to another person yet.

Level 2: Add any optional steps you didn't need this time

Most processes have steps which you only do some of the time. Take a moment now to add in any missing steps you didn't happen to need this time, but might have needed if the situation were different.

The result of this level is a complete set of ad-hoc bullet points which fully describe the process, including the optional or conditional steps. It's still fine for it to be messy and hard to understand by someone else at this point.

Level 3: Expand your notes into step titles

As we've talked about before, each step in a quality runbook has a title (aimed at experts) and a description (aimed at novices). You now want to expand your quick bullet points into proper titles. Since titles are aimed at experts, these should:

• be short (less than a dozen words)

• be complete, imperative sentences (i.e., a command)

• assume the reader has already done this many times before

The result of this step is a set of simple, clear imperative statements which would be good enough to remind a knowledgable person of which things to do, in what order. It may still be impossible for a novice to follow at this point.

Level 4: Add a description for each step

Now it's time to add the information a novice would need to correctly complete each step. It's easiest to do this by thinking of the last person you taught the process to (or the newest addition to your team), and imagine you are writing specifically for them. Here are some questions to help you figure out how much detail to include:

• What did they already know before they got here?

• What things were new to them?

• What's different about how this process is done here versus other places?

• Are there any screenshots, pictures, etc. which may be helpful?

• Is there some example you can provide for the reader to copy from (e.g., an email template)?

• Are there further resources outside the runbook you can link to?

The result of this step is the first complete draft of your new runbook. It will have everything needed by novices and experts alike to at least make a decent attempt at completing the process. It may still have typos, unclear sections, missing optional steps, or other minor problems.

Level 5: Refine the titles & descriptions

As you would do with any writing, now it's time to edit your work. Read through your runbook looking for all the same kinds of things you would look for with any other writing. In addition, you'll want to look out for these problems which specifically apply to runbooks:

• Do your titles address "how" to do it, rather than "what" to do? Issues of "how" belong in the description rather than the title.

• Do you include details which might change? People, phone numbers, email addresses, etc. are all things which often change. Instead, refer to roles (e.g., the IT admin), or a more generic way to contact the right person (e.g., a Slack channel).

• Do you use abbreviations or terms which are specific only to your company? Since these documents will often be read by newcomers, it's best to only use abbreviations or terms which are widely known in your industry. At a minimum, all such terms should be clearly explained when they are first used in each runbook.

• Do you make full use of images, bulleted/numbered lists, tables, and other formatting?

• Do your descriptions include more detail than is needed? You should aim to explain only those things a typical newcomer wouldn't already know about how you happen to do this process in your company. You don't want to duplicate reference material you could link to, or explain things most people in your field already know.

The result of this step is a refined draft of your runbook. It should be free of common errors (typos, grammatical errors, etc.), and should be well-targeted to the needs of both novices and experts on your team. It may still be missing steps you didn't discover in Levels 1 & 2.

Level 6: Perform the process again using the runbook

No matter how careful I am, I have never yet managed to write the perfect runbook on the first try. There's always something I forgot which I don't notice until I try to execute the runbook myself. So, now it's time for you to pretend to be the new person, freshly arrived, and attempting to perform this process for the very first time with only your runbook for guidance. Ideally, you'll do this the next time you really do have to perform the same work again. Here are some things to keep an eye out for as you go along:

• Is everything you're doing actually written down, or are you filling in pieces from memory?

• Do you actually do the steps in the order listed?

• Will a new person have all the tools and software you're using? Might they be using a newer version which works differently?

• Will a new person have the necessary access permissions and/or security clearance to perform each step?

• If a step goes wrong occasionally, have you included the usual workarounds in your runbook?

The result of this step is a runbook which has been validated against reality and is much more certain to be something others can use without your help. It may still be possible that other people won't understand the particular way you phrased things, or that you haven't accounted for variations in how different people do various steps.

Level 7: Ask another person to follow the runbook

The last step is to ask for someone else's help to repeat Level 6. They will almost certainly find some points of your writing unclear, and may have a better way to accomplish certain steps. Naturally, you'll want to ask them to keep an eye out for all the same things you were looking for, but to also mention:

• How does this runbook differ from how they perform the same process?

• Does the runbook accurately represent what needs to be done (i.e., no missing or extra steps)?

• Do they find anything confusing or unclear in the writing?

• Do the details in the descriptions (e.g., version numbers, phone numbers, email addresses, URLs, etc.) match with the ones they use?

The result of this step is your "final" draft of the runbook. But... not really "final". Any process should be constantly re-evaluated to make sure it remains complete, correct, and is still most efficient way to accomplish the goal. So, you'll want to revisit your runbooks periodically to check that nothing has changed.

We built our product, Runbooks, to make using this process as easy as possible. Keep a browser window open off to the side to take quick notes, fill in descriptions when you get to it, and ask your teammates for a quick opinion. Runbooks gives you all the tools you need to rapidly refine your runbooks to just the right level.

A runbook is a manual which serves as a reminder to a knowledgeable person of how to accomplish a specific goal. For example, you might have a runbook aimed at a recruiting team on how to set up an in-house interview loop for a candidate. There's a clear goal (the schedule is clear to all parties), there's a clear set of steps to get there, and it assumes the people executing those steps are knowledgable about the company's recruiting process. The runbook, then, serves as documentation of which steps are needed, and how they are supposed to be executed. That is, it's the extra stuff a knowledgable person would need to know how we do that here.

But, that's not where things should end. Such runbooks are gathered up in dusty binders to look pretty, unused, on a shelf somewhere to satisfy some ISO-9000 inspector. That's not what you need. You want something that your team can actually use to get better every day.

Once you have a good runbook, you now need what we call a "runlog". A runlog is copy of the runbook you create each time you perform the process it documents. It's the copy you scribble notes on as you work. It's the copy where you scratch out steps that don't apply, and sketch out alternate steps on the back of the page. If the runbook is the pristine copy that sits in a binder on the shelf, the runlog is the dog-eared copy on the clipboard that never leaves your side.

So, for example, if you have a runbook called "Set up an interview loop", you might have a runlog called "Set up Pat Smith's interview loop". It's the case of actually setting up one particular interview loop for a specific person. These runlogs are separate documents which serve as a live view on how the process is going. So, you'd be able to check off the steps as you go along, leave comments, add new steps as they come up, etc.

The usefulness of a runlog doesn’t end when the process is complete. With the live notes you collected, you now know what worked and what didn't work in the original runbook. Do you always skip a certain step? Was some instruction unclear? Do you always have to jot down an email address or telephone number? Re-incorporate those things back into your original runbook to save yourself the trouble next time. Over time, your runbooks will not only keep up with the changes to your team, but even improve and become more efficient.

Our product, Runbooks, is the only place you'll find both runbooks and runlogs, intimately tied together to create an unmatched integration of documentation and workflow. It wrangles the power of a good runbook into a form you team will actually use to get better every day.

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.

The other new feature is the ability to "clone" an existing runbook.  Perhaps you've got a few slight variants on a process, and you don't want to recreate the whole thing from scratch.  With a single button click, you can create a brand new runbook from an existing one.

As always, I love to hear your feedback on how Runbooks is working for you, and what you would like to see added in future releases!

— Andrew Miner

Release Notes

Features Added

• users can use a small toolbar to enter markdown formatting & upload images

• user can clone an existing runbook

Nuisances Remedied

• the text box for editing a description automatically resizes to fit its content

• the markdown help text didn't show how to upload an image to Runbooks

Bugs Fixed

• completed runlogs would sometimes fail to render their steps.

Operations Improved

• None

Tenet 1: Improvement requires consistency

Runbooks was founded on the idea that improvement requires consistency. If you want to be able to get better at something, you must first be able to repeat what you did last time. Otherwise, you randomly repeat errors from the past, and have one-off successes you can't duplicate again in the future. So, the first goal for a team that wants to get things right, is to figure out how to do it again.

Tenet 2: Consistency requires documentation

For any non-trivial process, consistency requires documentation. You can't count on someone's memory to get it right. Either there are too many steps, the steps are too complex, or it happens too infrequently to remember. That doesn't even account for turnover. If it's important enough to do right, it's important enough to do the writing.

Tenet 3: Documentation must be integrated

If you want people to read it, documentation must be integrated with your team's workflow. When people are busy getting their work done, they only ever go find the docs when they recognize they are confused and need help. Except that almost never happens after a person's first month on the job. Instead, they just muddle through and invent whatever process they like, ignoring all the learning built into the docs the team took so much time to create.

Tenet 4: Integration requires a purpose-built tool

No generic documentation tool (e.g., Google Docs, wikis, etc.) is going to have robust workflow. That's not what they're for, and anything which gets bolted on isn't worth using. No general workflow tool (e.g., Trello, JIRA, etc.) treats documentation as a first class feature. It's tucked away behind three links and a dialog or two, if it's present at all. To get both robust process documentation and workflow in the same place, you need a tool built to do exactly that.

If you want continuous improvement, check out Runbooks: the integrated tool purpose-built for writing and using runbooks.

What is a runbook?

A runbook is essentially a checklist. They can be very simple (a quick reminder of a few steps), or very formal (a pre-launch checklist at NASA). Some are a mere handful of bullet points, while others are robust documents with pictures, charts, and detailed instructions. They are often technical: but not always.

The thing they have in common is that they almost always meet one (or more) of these criteria:

1. there are more steps than you can easily memorize

2. it's mission (or safety) critical that each step be performed as specified and/or in a specific order

3. you only do the task at long enough intervals that you forget the details between each occasion

4. you need an audit trail of who performed (and/or signed off on) which steps

5. you need new people to be able to easily learn the procedure with little training

6. you have to perform the procedure accurately on short notice at awkward times

Examples

Most business have at least a handful of procedures which meet the criteria above, although many don't actually take the time to write them down. Here are some examples of runbooks I've used which match up with the list above:

1. Perform a manual test pass on Runbooks

2. Conduct a pre-flight inspection of a small aircraft

3. Drain and clean a hot-tub for the summer season

4. Perform a major product launch

5. Self-directed on-boarding for new employee

6. Respond to a "Disk is nearly full" alert on my servers

What to expect from this blog

In this blog, you can expect to learn about the best practices I and other experienced people have learned over the years for writing clear, concise, and useful runbooks. You can expect to learn about how those best practices are built in to Runbooks, and how to use the product to your team's best advantage. But, even if you aren't using our product, I hope you'll find this blog a source of inspiration of how to continuously improve your team's efficiency, productivity, and accuracy in everything you do.

I encourage you to sign up for weekly(ish) articles, tips, and advice.