The Documentation Set a Small Desk Actually Needs

Friday, 15:30, at Larkspur Dental. Ben has run the two-person desk for a four-surgery dental group for six years and has three weeks left before he leaves. The practice manager, Grace, has come to his desk with a reasonable question: "Where is everything written down?" Ben opens the knowledge base. It has a hundred and forty articles. He wrote most of them. He cannot, on the spot, say which fifteen matter or which forty describe systems the group no longer has. He cannot say whether the one Grace will need most is among them. That is what to do when the appointments system goes down on a Monday morning. He checks. It is not. It is in his head, where it has been perfectly safe for six years and will be useless in three weeks.

A documentation set is the minimum collection of written things a desk needs so that it can run for a fortnight on what is written down. The person who knows everything could be on a beach with no signal. The set is smaller than most desks fear and more specific than most desks have. For a desk of one to ten people it comes to five kinds of document. These are runbooks for the top problems, guides for the top questions, a scope page, a contact page and an outage page. This article is part of our Technician Docs vs User Docs series. This article puts the series' two kinds of document, and three more that are neither, into a list. Every row has a home and a name.

It covers why the set is smaller than you fear, then runbooks for the top problems and guides for the top questions. Next come the scope page, the contact page, and the outage page. It covers where each kind lives, who owns each, and what not to write yet. It ends with a short war story and the documentation inventory to copy, in that order.

Smaller Than You Fear

The documentation set is small because it is chosen by the queue, not by completeness. The queue on a small desk is dominated by a short list of recurring problems and a short list of recurring questions. The set documents those, plus the three pages that every requester needs regardless of their problem. Those pages cover what the desk does, how to reach it, and what is happening when something is down. Everything else is optional, and most of it is optional forever. A desk that tried to document everything would never finish. A desk that documents the top ten of each kind has written the pages that will be opened this month.

The test for whether the set is complete is the fortnight test. Imagine the person who knows the most is away for two weeks, unreachable, starting Monday. Walk through a typical Monday: a drive missing, a password that will not work, a new starter, a printer, the appointments system slow. For each, is there a page the remaining people can open and follow? Walk through a bad Monday: the main system down for an hour. Is there a page that says what to tell people and where? Where the answer is no, that is the next page to write. Where the answer is yes for everything you can think of, stop writing and start maintaining. Maintaining is the harder discipline and the subject of the knowledge base fundamentals series in this library.

For most small desks the set comes to twenty to thirty documents. Ten runbooks, ten guides, three pages, and a handful of pairs where a runbook and a guide describe the same procedure. Ben had a hundred and forty articles and did not have the set, which is the ordinary condition. Volume is not coverage. A knowledge base can be large and still have nothing in it about Monday morning.

Runbooks for the Top Problems

The runbooks are chosen from the queue by two measures: how often a problem arrives and how badly it goes when the wrong person handles it. Pull the last three months of tickets, group them by what the desk did about them, and sort by count. The top ten groups are the first ten runbooks, give or take the ones that are really guides. Then add the problems that are rare and dangerous: the main system down, the backup that did not run, the phone system silent. Those may arrive twice a year. And they are the ones the fortnight test fails hardest, because the person who knows what to do is the person who is away. Most help desk tools can produce the volume list in a minute. If you run QuerySolv, the reports on volume and on backlog by age are where the top-ten list comes from. The age report shows which problems are hanging around because nobody but one person can handle them.

Each runbook is written to the standard in Writing the Runbook. It is for a competent stranger, with assumptions, each action and its check, expected output, rollback, escalation and the date last run. It is visible to the desk only. On a two-person desk the competent stranger is the other person. On a one-person desk it is the contractor or the colleague from another department who covers the phones. Or it is the person who takes over when the one person leaves. The runbook is written for whoever that turns out to be. Ben's appointments-system runbook, when he finally wrote it, was for Grace.

The method for picking the first articles from the queue, with a worksheet for the top twenty ticket types, is in The First Twenty Articles. It applies here with one adjustment: the documentation set wants the top ten problems as runbooks and the top ten questions as guides. The worksheet's twenty rows usually sort themselves into roughly those two piles. Where a row is both, a problem users meet and the desk fixes, it is a pair. The pair is written as a runbook first and a guide derived from it.

Guides for the Top Questions

The guides are chosen from the questions users ask. That is a different list from the problems the desk fixes, and the difference is worth noticing. "How do I set up my out-of-office" is a question; nobody at the desk fixes anything. The user just needs to be told where the setting is. "My shared drive has disappeared" is a problem with a question in front of it; the user wants to know what to try before they raise a ticket. The top ten questions come from the same three months of tickets. This time the tickets are sorted by what the user asked rather than what the desk did. The questions also come from the desk's memory of what people ask in the corridor. Those questions never become a ticket and are therefore invisible to every report.

Where a guide is the user-facing half of a runbook, it is derived from the runbook by the method in the third article of this series. That means the safe subset, in the user's words, ending with a hand-off line. Where a guide stands alone, it is because the desk never performs the procedure for anyone. In that case, it is written directly, in the same plain style, and tested on one real user before it is published. Either way it is published, visible to everyone who can reach the portal, and has passed the leak test. A guide the users cannot reach is a runbook with a friendlier title.

Ten guides is a starting number, not a limit, and it will grow as the desk learns which questions deflect well. But the first ten are the ones that matter, because they are the ones that will be opened this month. A desk that publishes forty guides in its first fortnight has written thirty that nobody has asked about yet. Publish the ten, watch which are opened, and write the eleventh when the queue asks for it.

The Scope Page

The scope page says what the desk supports, what it does not, and what happens when someone asks for something in the second list. It is one page, published, and it is read by users deciding whether to ask and by technicians deciding whether to say no. Without it, every ticket about a personal phone, a home printer or a piece of software nobody approved is an argument. The argument is had afresh each time, by whoever picked up the ticket, with whatever answer they felt like giving. With it, the answer is a link.

The scope page is not a service catalogue and should not try to be one. It lists the systems and services the desk supports in plain words and the things it explicitly does not. It lists the grey areas with who decides, and the route for asking for something new. The words to use, and how to say what you support without writing an eleven-page policy, are in Saying What You Support. The documentation set needs only that the page exists, is current, and is the page every "do you support this?" ticket is answered with. It is owned by the desk lead, because scope is a decision and the lead is the person who makes it.

The Contact Page

The contact page says how to reach the desk, when it is staffed, what to put in a request so it can be worked, and what happens after a request is sent. It is the most-opened page the desk will ever publish, and the one most desks never write because everyone assumes everyone knows. New starters do not know. Contractors do not know. The person covering reception on a Saturday does not know, and will phone the technician whose number is on an old poster. That is why the contact page exists and the old poster should not.

The page lists every door the desk accepts requests through: the portal, the e-mail address, the chat, the phone. It says which to use when. It says the hours, and what happens outside them. It says what to include, which is the two or three facts the desk always ends up asking for. And it says what the requester will get back and when, which is the acknowledgement and the first human reply. The reason to list every door and say they all lead to the same place is in One Queue, Many Doors. The contact page is where the user finds that out. It is owned by the desk lead and reviewed every time a door opens or closes. That is less often than the scope page changes and more often than anyone remembers.

Do not put a person's name or direct number on the contact page. Names leave. The page says "the desk", and the desk's rota, which is not published, says who the desk is today. The one exception is the out-of-hours arrangement, if there is one. Even then the page gives the number of the on-call phone, not the person carrying it.

The Outage Page

The outage page is the one page that is updated during an incident. And it is the only document in the set that is written before it is needed and rewritten in a hurry every time it is used. On a quiet day it says "all systems normal" and the date it last said so. During an outage it says what is down, who is affected, what to do in the meantime, and when the next update will be. After the outage it says what happened and that it is over. The whole mechanism, with cheap ways to have such a page and what must never be on it, is in A Status Page for a Small Organisation. The documentation set requires only that it exists, that everyone knows where it is before the outage, and that the words for the first notice are already written.

The pre-written part is the point. At 08:05 on the Monday the appointments system goes down, the person updating the page should be filling in blanks, not composing. The set therefore includes, beside the page, a template for the first notice, the update, and the all-clear. It has blanks for the system, the time and the next update. It is kept where the person on duty can find it in ten seconds. On a small desk that person may be the receptionist. The template is written so that the receptionist can use it, which is to say it is a user guide for the desk's own worst morning.

The outage page is owned by the desk lead and rehearsed. That sounds grand and means that once a quarter somebody posts a test notice on it, in a planned window. The test checks that the page can still be edited by the people who will need to edit it. It also checks that the words still make sense. An outage page nobody has edited in a year is a page whose login has expired, and that will be discovered at 08:05.

Where Each Lives

Each kind of document has one home, and the homes are decided by who reads it. Runbooks are visible to the desk only, as agents-only articles in the knowledge base or, where the tool has no such setting, in one internal folder with one file per procedure. Guides, the scope page, the contact page and the outage page are published, visible to everyone who can reach the portal. The three pages are pinned or linked from the portal's front page so that nobody has to search for the page that says how to search. The outage page may also live somewhere that stays up when the portal does not. That is the one case where a document in the set has two homes, and the second home is written on the first.

The "one home" rule is the rule most often broken and most worth keeping. A runbook that exists in the knowledge base and in a shared folder and in the lead's personal notes is three runbooks, two of which are wrong. A contact page that is also a poster, a footer in the e-mail signature and a slide in the induction deck has four versions. And the poster will outlive the phone number by years. Pick the home and put the document there. Make everything else a link to it or a copy with the words "see the portal for the current version" printed larger than the content.

The table below is the whole set at a glance. It shows the five kinds, who reads each, where each lives, who owns each, how often it is reviewed, and roughly how many a small desk needs. It is the reference half of this article; the inventory at the end is the working half.

Who Owns Each

Every document in the set has one name on it, and the name is a person who will notice when the document is wrong. For runbooks that is the technician who looks after the system, because they are the one who will run it and find the step that changed. For guides derived from runbooks it is the same person, because the pair has one owner. For standalone guides, the scope page, the contact page and the outage page it is the desk lead. That is because those pages are decisions about the desk rather than facts about a system. The lead is the person who makes them. On a one-person desk every name is the same name. The inventory still gets written, because the point of the name is that it changes when the person does.

Ownership is recorded on the inventory, not only on the document, because the inventory is what the next lead opens on their first day. Ben's hundred and forty articles each had his name on them, which told Grace nothing she did not know and nothing she could use. The inventory he wrote in his last three weeks had twenty-six rows, each with a kind, a home, a name, and a last-reviewed date. Eighteen of the names were Grace's. It was the first time she had seen them written down and the first time she understood what she was taking on. The inventory is the handover. The articles are what it points to.

What Not to Write Yet

Do not write the architecture document, the network diagram with every cable, the policy manual or the complete service catalogue until the set exists. None of them will be opened on the Monday the lead is away and all of them take longer than the set. Do not write a runbook for a problem that has happened once, unless the once was catastrophic. Do not write a guide for a question nobody has asked, however obvious it seems that they will. Do not write the eleventh runbook before the first ten have been run by someone other than their author. An unrun runbook is a draft with a confident title.

Do not, above all, write the set into a hundred and forty articles. A desk that documents everything it knows has produced a place where the set is hidden among its own notes. And the fortnight test fails not because the pages are missing but because nobody can find them. The set is small so that it can be found, kept current and handed over. Everything else the desk knows can be written down later, once the set exists and is being maintained, in a place clearly marked as everything else.

A Short War Story: The Hundred and Forty Articles at Greyfriars Architects

Greyfriars Architects, a practice of ninety people across two offices, had a one-person desk run by a technician called Marcus. He left at short notice and handed over a knowledge base of a hundred and forty articles. He also handed over a shared folder of sixty documents and a personal notebook. None had an index. His successor, Yusuf, spent his first three weeks reading all of it to find out which systems still existed. In the second of those weeks the drawing-file server lost a disk on a Tuesday afternoon. Dealing with that was a procedure Marcus had done twice and documented nowhere. So Yusuf rebuilt it from the supplier's manual over two days. While he did, forty architects worked from copies on their laptops and two tender submissions went out late. When he finished reading, Yusuf found that twenty-two of the two hundred documents were the set. There were nine runbooks, eight guides that users had actually opened, and a scope page from four years earlier. There was a contact page with Marcus's mobile number on it, and no outage page at all. That was why on the Tuesday he had told people by walking between desks. He built the inventory from those twenty-two. He wrote the three runbooks the fortnight test said were missing, including the disk one, and replaced Marcus's number with the desk's. He archived a hundred and seventy documents with a note saying where they had gone. The handover had been two hundred documents and no list. Two days of a practice's time had been spent discovering that the one page it needed had never been written.

The Documentation Inventory

The inventory below is the template for this article: one page that lists the set, row by row, with the kind, the home, the owner and the dates. Build it in one sitting from the fortnight test and the top-ten lists. Mark the rows that exist and the rows that do not. Work through the missing ones in the order the test says. Keep it where the desk keeps its other registers and review it at the quarterly sweep. Hand it, not the knowledge base, to the next person who runs the desk. The "found elsewhere" section at the bottom is for the documents that turn up in folders and notebooks during the build. Each is either moved into the set, archived with a note, or left where it is with a line here saying so.

DOCUMENTATION INVENTORY — ONE PAGE
Desk: ______________   Kept by: ______________   Last reviewed: ________
Fortnight test last walked: ________   Rows missing: ____   Rows stale: ____

RUNBOOKS FOR THE TOP PROBLEMS (agents only)
  RB-__  ______________________________  owner ________  last run ________  [ ] exists
  RB-__  ______________________________  owner ________  last run ________  [ ] exists
  RB-__  ______________________________  owner ________  last run ________  [ ] exists
  RB-__  ______________________________  owner ________  last run ________  [ ] exists
  RB-__  ______________________________  owner ________  last run ________  [ ] exists
  Rare but dangerous (main system down, backup failed, phones silent):
  RB-__  ______________________________  owner ________  last run ________  [ ] exists
  RB-__  ______________________________  owner ________  last run ________  [ ] exists

GUIDES FOR THE TOP QUESTIONS (published)
  G-__  _______________________________  paired with RB-__  owner ________  [ ] exists
  G-__  _______________________________  paired with RB-__  owner ________  [ ] exists
  G-__  _______________________________  standalone         owner ________  [ ] exists
  G-__  _______________________________  standalone         owner ________  [ ] exists
  G-__  _______________________________  paired with RB-__  owner ________  [ ] exists
  (one row per guide; leak test passed before publishing: [ ] all)

THE SCOPE PAGE (published, linked from the portal front page)
  Location: ______________  owner ________  last reviewed ________  [ ] exists
  Says: what we support [ ]  what we do not [ ]  grey areas and who decides [ ]
        how to ask for something new [ ]

THE CONTACT PAGE (published, linked from the portal front page)
  Location: ______________  owner ________  last reviewed ________  [ ] exists
  Says: every door and when to use each [ ]  hours and out-of-hours [ ]
        what to include in a request [ ]  what happens next and when [ ]
  Contains no person's name or direct number: [ ]

THE OUTAGE PAGE (published; second home that stays up: ______________)
  Location: ______________  owner ________  last test notice ________  [ ] exists
  Editable by whoever is on duty, checked: [ ]
  Templates beside it: first notice [ ]  update [ ]  all-clear [ ]

FOUND ELSEWHERE DURING THE BUILD
  ______________________________  in ______________  [ ] moved into set
  ______________________________  in ______________  [ ] archived, note left
  ______________________________  in ______________  [ ] left; reason: ________

HANDOVER
  Next person reads this page first: [ ]   Every owner name still employed: [ ]

Ben filled the inventory in over his last three weeks at Larkspur Dental. It came to twenty-six rows. Eleven of them existed and were current, nine existed and were stale, and six did not exist. The missing ones included the appointments-system runbook, which he wrote on the second Tuesday with Grace reading each step back to him. The contact page had his mobile number on it; it now has the desk's. The hundred and forty articles are still there, in a section called "Archive: read the inventory first". Grace has not needed to open it. The appointments system went down on a Monday five weeks after he left. The runbook took her eleven minutes, and the outage page said so.

Frequently Asked Questions