Writing the User Guide From the Runbook, Not From Scratch

Thursday, 10:15, at Bluewater Bank. Nadia runs the branch desk. A manager with the best intentions has asked her to "make the card printer article user-friendly so the branches stop ringing". The article in question is a runbook: nine numbered steps, each with a check and an expected output. They run from "confirm the printer shows online in the management page" through "reseat the ribbon, left spindle first". They end at "if the jam light stays on after two cycles, escalate to the supplier with the serial number". It is a good runbook. Nadia ran it herself last month. She has it open on one screen, a blank page on the other. Which of these nine steps can a cashier with a queue of customers safely be asked to do? The instructions must use words a cashier uses, without a management page, a spindle diagram or a supplier number.

That question is the whole of this article. A user guide is the safe subset of a procedure, written in the user's words, ending where the desk takes over. The reliable way to write one is to derive it from the runbook rather than to compose it fresh. The runbook is the tested truth about the procedure and a guide that starts from it inherits the truth. This article is part of our Technician Docs vs User Docs series. It is the second half of a pair. The first half, the runbook itself, is in Writing the Runbook. This one assumes a runbook exists.

It starts with why the guide starts from the runbook and not from a blank page. Then come finding the safe subset, what to remove, what to add, and plain words and one action per step. Next is the same procedure side by side with what moved. Then come the hand-off line where the guide ends and the ticket begins, and testing it on one user before publishing. A short war story and the derivation checklist to copy finish the article.

Start From the Runbook, Not a Blank Page

The guide is derived, and the reason is consistency. The runbook was written from a real ticket, run on a real system, corrected on the next run, and carries the date it was last seen to work. A guide derived from it inherits all of that: the order of the steps, the expected result after each, the point at which the procedure stops being safe. A guide written from memory, by whoever was free that afternoon, inherits that person's memory. That may be of the procedure as it was two years ago, or as they imagine it. Or as it works on their own machine, which has rights the cashier's does not.

Derivation also keeps the pair honest later. When the runbook changes, the guide must change. The only way anyone will know what to change in the guide is if the guide's steps map onto the runbook's. Step two of the guide is step one of the runbook, reworded; step three of the guide is where the runbook's step four begins and the user stops. With that mapping written down, a change to runbook step four is a one-minute check of the guide. Without it, the change is an afternoon of reading both documents and guessing. The mapping is kept in the sync register, which is the subject of the fourth article in this series; here the job is to create it.

So the first move is mechanical: copy the runbook into a new draft, visible to agents only, with "GUIDE DRAFT" at the top, and work on the copy. Every line in the copy is either kept and reworded, removed, or replaced with something added for the user. Nothing is invented from nowhere. By the end, the draft has shrunk from nine steps to three or four. Every one of them can be pointed back at the line of the runbook it came from. That is a guide that can be maintained. The other kind can only be rewritten.

The Safe Subset

The safe subset is the set of runbook steps that a user can do with their own account, that cannot make anything worse if done wrong, and whose result they can see for themselves. All three conditions must hold. "Sign out and sign back in" passes: any account can do it, it harms nothing, and the user can see whether the drive is back. "Clear the print queue from the management page" fails all three. It needs a login the user does not have, it can delete other people's jobs, and the user cannot tell whether what they cleared was the problem. "Switch the printer off, wait ten seconds, switch it on" passes two and a half. The half is the question of whether anyone else is printing, which the guide can handle by saying "if nobody else is printing".

Go down the runbook step by step and ask the three questions of each. Can a user do this with the rights they have? If they do it wrong, what happens? Can they tell whether it worked? Write the answers beside each step. On most runbooks the safe subset is the first two or three steps, which are usually the cheap checks and restarts. Then comes a wall, which is the first step that needs a console, a command or a server. The guide stops at the wall. Everything after the wall belongs to the desk, and the guide's last line says so.

Be strict about "cannot make anything worse", because it is the condition people relax first. A step that is harmless on the technician's machine can be harmful on the user's, where a setting is different or a right is missing. A step that is harmless done once can be harmful done five times by a user who did not know it had worked. When in doubt, the step is not in the subset. A user guide with two steps that are certainly safe is worth more than one with six steps where one is a risk. On a bad day, that one might take the branch offline. (The branch will find the bad day. It always does.)

What to Remove

Remove every step past the wall. Remove the assumptions block, because the user's assumptions are "I have my own account and I am at my desk" and need not be stated. Remove the checks that need a console or a log. Keep only the checks the user can make with their eyes: the drive is back, the printer's light is green, the page loads. Remove the rollback, because the safe subset has nothing to roll back; if it did, it was not safe. Remove the escalation section and replace it with the hand-off line, which is the user's version of escalation and is described below.

Remove every name the user does not need. That includes server names, service names, the management page's address, and the supplier's name and reference. It includes the runbook's own identifier and the names of colleagues on the rota. None of these helps the user and several of them should never be in a published document at all. The list of what must never appear in a user-visible article, with a test to run before publishing, is in What Must Never Be in the User Document. The derivation is the moment most of those leaks are prevented. The names are in the runbook you copied and will be in the guide unless you take them out.

Remove the cause. The runbook may explain why the share service stops, because the technician needs to know whether this is the recurring fault or a new one. The user does not need to know and will not be reassured by it. "This sometimes happens after the overnight backup" is interesting to the desk and alarming to a cashier, who now wonders what else the backup does. The guide says what to do and what they will see. The why stays with the people who can act on it.

What to Add

Add the symptom in the user's words, as the title and the first line. The runbook is titled "File share not reachable from workstations". The guide is titled "My shared drive has disappeared", because that is what the user will type into the search box and what they will say on the phone. The first line confirms they are in the right place: "The folder you usually open from the drive list is not there, and you have not changed anything." A user who reads that and nods will follow the steps. A user who reads a technician's title will keep searching, or stop.

Add what they will see after each step. The runbook's expected output becomes the guide's "what you will see", in the user's terms: not "status: running" but "the drive letter is back in the list". This line is what lets the user know whether to continue. It is the single most common omission in guides written from scratch, which tend to give the steps and leave the user to judge success. Add how long it takes, in total, at the top: "about two minutes". A user who knows it is two minutes will try it; a user who does not know will phone first and try later, if at all.

Add the reassurance that the steps are safe, once, in a sentence: "none of these steps will lose any files or change your settings". The user is being asked to act on trust, and a line that says the action is harmless is what earns the trust. Add what to have ready for the ticket if the steps do not work, which is the hand-off line. And add nothing else. A guide that grows an introduction, a troubleshooting section and a list of related topics is a runbook growing back. The table below is the whole derivation in one place: each element of the runbook and what happens to it on the way to the guide.

Plain Words, One Action per Step

Every step in the guide is one action, in words the user already uses, with no term the user would have to look up. "Sign out of your computer, then sign back in" rather than "log off and re-authenticate". "The folder you usually open from the drive list" rather than "the mapped network share". Where a technical word is unavoidable, because it is on the user's screen, use it exactly as the screen shows it. Say where it is: "click the button labelled Reconnect, which is in the top right". The craft of a step a frustrated reader can follow is in Step-by-Step Clarity: One Action per Step. That article includes why one action per step matters so much when the reader is already upset. The guide should be written to that standard without exception.

Plain words are not fewer words. "Restart" is a plain word that means four different things to four users: switch it off at the wall, close the program, sign out, or press the power button until something happens. The guide says which: "switch the printer off using the button on its side, wait ten seconds, switch it on, and wait until the small screen shows Ready". That is longer and clearer. Shortness that costs clarity is not plainness; it is a runbook's habit of brevity transplanted into a document whose reader cannot fill in the gaps. The way to replace jargon with something a user can act on, without talking down to them, is in Skipping the Jargon Without Dumbing It Down.

Read the finished steps aloud, as if to a colleague in another department, and listen for the word you would have to explain. There is always one. It is usually a word so familiar to the desk that nobody noticed it was a word. I once published a guide that told users to "clear the cache" and received eleven tickets asking where the cache was kept. It was a fair question, and one I had not thought to answer because I had never had to ask it.

The Same Procedure, Side by Side

The picture below shows a missing shared drive as a runbook and as the guide derived from it. On the left, the runbook: assumptions, the symptom, a sign-out step, a check on the share service, a restart with its expected output, the rollback, the escalation and the last-run line. On the right, the guide: the symptom reworded, the sign-out step reworded, and four lines that were not in the runbook at all. Those lines say what the user will see, when they are done, and what to do if they are not. The dots mark each line's fate: green was kept and reworded, red was removed and stays in the runbook, blue was added for the user. Eight runbook lines became six guide lines, and only two of them came across.

Two things in the picture are worth saying in words. The guide is shorter than the runbook, and it should be; a guide that is as long as its runbook has kept something it should have removed. And the guide has more blue than green, which is normal. Most of a good guide is the material added for the user, because the runbook's steps were never the hard part for the user. Knowing whether it worked and what to do next was.

The Hand-Off Line

The guide ends with the hand-off line: the sentence that tells the user the steps are over and the desk takes it from here. It says what to put in the ticket so the desk can start at the right step. "If the drive is still missing, raise a ticket and tell us which drive letter is gone and that you have already signed out and back in." That last clause is the point. A ticket that arrives saying "already tried signing out" lets the technician open the runbook at step two instead of step one. On a busy morning that is the difference between a two-minute ticket and a six-minute one with a phone call in it.

Write the hand-off line to collect exactly what the runbook's first unsafe step needs. If runbook step four needs the printer's label number, the hand-off line asks for the label number and says where to find it. If the runbook's recognition test needs to know whether anyone else is affected, the hand-off line asks "is it just you, or your colleagues too?". The guide is, in this sense, the desk's best intake form. It reaches the user at the moment they have the problem in front of them. It asks for the two facts the desk would otherwise have to ask for by e-mail the next day. Suppose every door into the desk, the web form, e-mail and chat, lands in the same queue as an ordinary ticket, as it does in QuerySolv. Then the hand-off line can simply say "raise a ticket" without caring which door the user prefers.

Never let the hand-off line apologise, hedge or offer a third option. "You could also try restarting your computer, or ask a colleague, or wait and see" is three more things to do before the ticket. Each one delays the desk's involvement in a problem the desk has already decided it should handle. The guide tried the safe things. They did not work. The next step is a ticket, and the guide says so in one sentence, kindly, and stops.

Test It on One User Before Publishing

Before the guide is published, one real user follows it, in front of someone from the desk, without help. Not a technician pretending to be a user, who will fill in every gap without noticing. A person from the department that raises the tickets, with their own account, on their own machine, reading it for the first time. Watch where they pause. Where they pause, the guide is unclear. Where they ask a question, the guide is missing a line. Where they do something the guide did not say, the guide's step was ambiguous and they chose the other meaning.

The test takes ten minutes and finds the one word, the missing "what you will see", and the step that needed a right the user did not have. That last one would otherwise have generated the "access denied" tickets. Fix what the test found, in the draft, and then publish. The method for running such a test without making the user feel examined, and for what to do with what it finds, is in Testing Articles on Real Users. Do it for every guide. Yes, even the two-step one. The two-step one is where the word "restart" lives.

A Short War Story: The Guide Written From Memory at Northgate Retail

Northgate Retail's desk had a solid runbook for "Till will not connect to the back office". A regional manager called Colin had once watched a technician fix it. He wrote a user guide for store staff from memory over a weekend and asked the desk to publish it. The desk did, because it was Monday and Colin outranked everyone on it. Step four of Colin's guide told staff to "open the till's network settings and re-enter the store code". The technician had done that step with an engineering login that store staff did not have. The following week sixty-three stores reported "access denied" at step four. Each ticket also described three other things the guide had told them to try first. The tickets took longer than tickets from stores that had read nothing. Each one began with a technician undoing what step three had done to the till's display settings. That step had never been in the runbook at all; Colin had remembered it from a different printer. The desk withdrew the guide and derived a new one from the runbook with two steps and a hand-off line asking for the till number. It had a store supervisor try it on a Tuesday afternoon, and published that. The next month had nineteen till tickets, every one of them starting at runbook step three with the till number already in it. A guide not derived from the runbook is a memory with a publish button, and memory does not know which steps need a login.

The Derivation Checklist

The checklist below is the method of this article in a form that fits on one page. Work through it on the copy of the runbook before the guide is published. Fill in the mapping at the bottom, because it is what makes the pair maintainable later, and keep the completed sheet with the runbook rather than on the portal. The three questions in the first section are the ones that decide the safe subset. The line that asks what the user does if they do a step wrong is the line to answer honestly.

DERIVATION CHECKLIST — RUNBOOK TO USER GUIDE
Runbook: RB-____  Title: ______________________________________________
Guide draft (agents-only until published): ____________________________
Derived by: ______________   Date: ________

1. THE SAFE SUBSET (ask of every runbook step)
   Step __  Can a user do it with their own rights?    [ ] yes  [ ] no
            If done wrong, what happens? ______________________________
            Can the user see whether it worked?          [ ] yes  [ ] no
            In the guide?  [ ] yes  [ ] no (this is the wall: stop here)
   (repeat for each step until the first "no")

2. REMOVED (tick when gone from the draft)
   [ ] Assumptions block        [ ] Checks needing a console or log
   [ ] Every step past the wall [ ] Rollback section
   [ ] Escalation section       [ ] Cause and history
   [ ] Server, service, supplier and colleague names
   [ ] Runbook ID, last-run line, management page addresses

3. ADDED
   [ ] Title is the symptom in the user's words: _______________________
   [ ] First line confirms "this is you if ..."
   [ ] Time it takes, at the top: about ____ minutes
   [ ] One sentence saying the steps are safe
   [ ] "What you will see" after every step
   [ ] Hand-off line: raise a ticket and tell us ________________________
       (collects what runbook step ____ needs first)

4. WORDS
   [ ] One action per numbered step
   [ ] No term a user would have to look up; screen labels quoted exactly
   [ ] Read aloud; the word that needed explaining: ____________ fixed [ ]

5. TEST
   Tried by (name, department): ______________   Date: ________
   Where they paused: ______________________   Fixed [ ]
   What they asked: ________________________   Fixed [ ]
   Step they could not do: _________________   Removed [ ]

6. MAPPING (keep with the runbook; goes in the sync register)
   Guide step 1 = runbook step ____     Guide step 3 = runbook step ____
   Guide step 2 = runbook step ____     Guide ends before runbook step ____

Published on: ________   Published by: ________   Review with runbook: [ ]

Nadia worked the sheet against the card printer runbook on the Thursday afternoon. Of nine runbook steps, two survived: switch the printer off and on, and check whether the jam light has gone out. The guide was titled "The card printer has a red light and will not print". It took about three minutes and said the two steps would not lose anything. It ended with "if the light is still red, raise a ticket and tell us the printer's number from the sticker on its side". A cashier at the flagship branch tried it and paused at "switch it off", because there were two buttons. The guide now says which one. The branches still ring, but less, and when they do, the ticket has the printer number in it.

Frequently Asked Questions