Documentation as Your Second Person

It is 16:40 on the Friday before two weeks of leave. You are writing the document that has to be you while you are gone. Not a description of you. A working copy: where the backups land, which printer wants the old driver, who to call when the phone system stops forwarding to cell phones. The out-of-office reply took two minutes. The document has taken four attempts, because each attempt was interrupted by a quick question. A quick question is a ticket that has not yet admitted it.

Nobody plans to be the only person who knows how the desk works. It happens the way shared folders happen, one reasonable thing at a time. This article is the fourth in our One-Person IT Department series. It is about the only second person a solo administrator can hire without a budget line. That is the written one. Running Support Solo set out the operating model. Boundaries for the Solo Admin drew the lines that keep it survivable. This one is about what happens to the desk when you are not in it.

It covers the three documents that cover one person: the runbook, the knowledge base and the estate page. Then comes the plane test, which is the hit-by-a-bus test with the bus taken out. Next are the ten-minute habit that writes the documentation while you solve the ticket, the cover person, and keeping the documents alive. A worked week before leave and a war story from a bank branch follow. Finally, there is a template for the estate page and the runbook's first page.

The Three Documents That Cover One Person

A solo desk is covered by three documents, and they answer three different questions. The runbook answers how the desk runs. It says where tickets come from, when they are looked at, and what a reply must contain. It also says what the cover person may and may not touch. The knowledge base answers how problems get solved: the symptom, the cause and the fix for each thing that has broken before. The estate page answers what exists: every system, who owns it, which vendor supports it, when the contract ends, where the keys are. Three documents, three questions, and a desk that can be run for two weeks by someone who has never run it.

They are kept separate because they are read by different people at different speeds. The runbook is read once, slowly, by the cover person on the morning you leave. The knowledge base is read in a hurry, one article at a time, with a ticket open. The estate page is read in a worse hurry, by someone who needs to know whether the thing that just went dark has a support contract. A single document that tries to be all three becomes forty pages. Forty pages is where documentation goes to be unread.

Most solo desks have one of the three, usually the knowledge base, because that is the one the ticket tool nags about. The runbook lives in your head, which is a fine place for it until the head is at the airport. The estate page lives in a spreadsheet from a previous administrator, last updated when the office had a different address. Fill the gaps in this order: estate page, runbook first page, everything else.

The Plane Test

The plane test asks one question of every document. Could a competent person run this for two weeks while the one who knows it is on a plane with no internet? The older version involves a bus, and it makes people flinch instead of think. The plane version sets the stakes where they belong: an eleven-hour flight, a hotel with bad wifi, and a desk that has to keep going anyway. The person who knows everything is going to be on that plane sooner or later. You should want them to be. That is what leave is for.

Run the test by reading each document as the cover person rather than as the author. The author knows that "restart the service" means the one on the second server, in a particular order, after checking that the queue is empty. The cover person knows none of that, and will restart the wrong service in the wrong order with the queue full. Every place where you would have to say "well, what I actually do is" is a gap, and the gaps are the document.

The test fails in a predictable place, and it is almost never the complicated thing. The complicated thing got written down because it was complicated. What fails is the ordinary thing done a particular way for a reason nobody recorded. There is the payroll freeze on the twenty-fifth or the account that must not be touched. There is the printer called "Finance 2" on its label and "FIN-PRN-01" on the server. I have failed the plane test twice, both times on something I would have called too small to write down. It was not too small. It was too familiar.

The Runbook: How the Desk Runs

The runbook is the operating manual for the desk itself, and its first page is the part that matters. The first page says where tickets arrive and how to see them. It says when to look at the queue (09:00 and 14:00, say) and what to do at each look. It says what every reply must contain. It also says what the cover person may change, what they must not, and who to call for the rest. Everything after it is detail to be looked up. The first page is what the cover person reads at 08:50 on Monday with a coffee, and it should fit on one screen.

A runbook for a solo desk has one rule the three-person version does not need: it must say what to leave alone. A cover person with full rights and good intentions is the most powerful thing on your network for two weeks. The runbook names the hands-off systems (payroll, the domain controllers, anything under a vendor contract) and the number to call instead. "Do not touch, call this person" is a complete instruction. The cover person will be grateful for it, because it is also permission not to be a hero.

The rest of the runbook is the solo operating card from the first article in this series, plus the sentence after each line that says why. The why is what lets the cover person make a sensible decision about the case the card did not foresee. There is always one.

The Knowledge Base: How Problems Get Solved

The knowledge base is a collection of short answers to specific problems. On a solo desk it serves two audiences from one place. User-facing articles tell the person with the problem what to try before they open a ticket. Agent-facing articles tell the person with the ticket what the fix is. That is the kind that covers you. The cover person will search it with a ticket open and a user waiting. An article for them needs the symptom in the user's words, the cause in yours, the steps in order, and the ticket number it came from.

Keep the articles short and the titles literal. "Label printer in the warehouse prints blank pages" is a title the cover person will find by searching the words in the ticket. "Printer issues" is a title nobody will find, because it is every printer and every issue. A hundred and fifty words covers most fixes; past that you are writing two articles.

The agents-only articles hold the embarrassing truths. There is the workaround that should not be necessary or the server that needs a restart every second Sunday. There is the vendor contact who answers on the third attempt. They are true, they are useful, and the user does not need to see them. A knowledge base that can keep an article visible to agents and invisible to requesters lets you be honest in it. One that cannot fills up with articles that are polite and useless.

The Estate Page: What Exists and Where the Keys Are

The estate page is a single page that lists everything you are responsible for. It follows the order a stranger in an outage would need: systems, owners, vendors, contracts, and where the keys are. Each line is one system. It gives the system's name on the label and on the network, what it does, and where it runs. It names who in the business owns it, which vendor supports it and how to reach them. It also says when the contract or warranty ends and where the credentials live. The last column never contains a password. It contains the name of the vault entry where the password is.

The column order is the order of a stranger's questions in an outage. What is this thing? Who do I tell? Is anyone obliged to help me? And only then, how do I get in? Put the keys first and the page becomes a list of doors with no map.

The estate page is also where the budget meets the floor. The line says "backup appliance, warranty ends next month". Two quarters later, the same line tells the manager that the appliance is out of support and nobody noticed. I keep mine with the contract end dates sorted to the top, so that the next expiring thing is the first thing anyone sees. The page has saved a renewal three times. It has never once been read for pleasure.

Writing While Solving: The Ten-Minute Habit

The habit that builds all three documents is ten minutes of writing at the end of any fix that took more than twenty. Twenty minutes is the line because a fix under twenty was either trivial or already written down. A fix over twenty cost you something you do not want to pay twice. The ten minutes go into the ticket first, as a note a stranger could follow. Then they go into the knowledge base if the problem could recur. If the fix revealed something about the estate (a server you did not know about, a contract you did not), that goes on the estate page before the ticket closes.

Write it while it is fresh, in the same sitting, before the next ticket. The fix you finished at 14:10 is fully in your head at 14:30 and half gone by Thursday. Written on Thursday it will be shorter, vaguer and missing the step that was the actual problem. That is the step you are most likely to forget because it surprised you. I have reconstructed my own fixes from my own ticket notes and found them unhelpful. That is a humbling way to learn this.

The habit costs about an hour a week and pays it back the first time the problem returns. It always returns. A twenty-minute fix repeated by the person who did it last time is twenty minutes. The same fix done by a cover person with no article is two hours. It also means a phone call to someone who is supposed to be on leave. Automate the First Ten Tickets takes the idea one step further. Once a fix is written down, the next question is whether it needs a human at all.

The Cover Person

The cover person is whoever runs the desk when you are away. On most solo desks it is one of three people. It might be a colleague from another department who is handy with computers, your manager, or a contractor on a day rate. None of them is an administrator. All of them can run the desk for two weeks from a good first page, a knowledge base and an estate page. That depends on the runbook saying what not to touch. The three documents exist to make the cover person's lack of expertise survivable, not to make them an expert.

What they need from you is short. The runbook's first page, read together, in person, a week before you leave. A ticket-tool login with rights to work tickets and none to change the system. The estate page, the emergency definition and the call list. They also need one sentence, in writing, from your manager. It says that they are covering IT for two weeks and may tell people that a thing can wait. The last item is the one most often skipped. That sentence is the one that stops the hallway from routing around the cover person and straight to your cell phone.

Choose the cover person for temperament over knowledge: calm, follows written instructions, asks before acting, and comfortable saying "I don't know, I've logged it". Calm plus a good first page closes thirty tickets and leaves the hard ones for you, which is the correct outcome. Confidence plus no documentation produces changes, and changes produce the phone call.

The Week Before You Leave, Worked Through

Here is the week before leave as Dana ran it at Meridian Parts, a distribution company of about ninety people. Dana is the whole IT department and Marcus from finance is the cover person. Dana's leave started on a Monday.

On the Monday before, Dana spent ninety minutes on the estate page: forty-one lines, each with an owner, a vendor and a vault entry name. Eleven lines had no vendor contact on record, so Tuesday morning went on finding them. That turned up two support contracts that had lapsed without anyone noticing. On Tuesday afternoon she wrote the runbook's first page in about an hour.

On Wednesday at 10:00 Dana and Marcus read the first page together. Then they walked the server room while Dana pointed at things on the estate page. Marcus's ticket-tool account got agent permissions, not administrator ones. On Thursday Dana changed nothing, on purpose. She wrote six knowledge articles for the six fixes that had taken more than twenty minutes in the past month. On Friday at 15:00 she handed over seven open tickets with a one-line note on each. She switched on the out-of-office reply and left at 16:30. That is early for a Friday before leave and exactly the point.

Two weeks later, Marcus had closed thirty-four tickets. He had escalated two to vendors using the numbers on the estate page and called Dana's cell phone zero times. The one ticket he could not close was waiting on the vendor whose lapsed contract Dana had found on the Tuesday. The preparation took about two working days. It bought ten quiet ones.

Keeping the Three Documents Alive

Documentation dies by drift, not by deletion. The server gets renamed. The vendor gets bought. The printer gets replaced and the article about it stays, confidently describing a machine that is now a doorstop. The defense is two habits, a quarterly read-through and the leaver test. And both are cheaper than discovering the drift from the cover person, by phone, during your leave.

The quarterly read-through is a calendar appointment, an hour long. Read the estate page top to bottom and change what has changed: contracts ended, owners moved on, systems retired, vault entries renamed. Then read the runbook's first page, with one question: is this still what I do? It usually is not quite. A new system has arrived and is not on the hands-off list. Fix it there and then. A document reviewed quarterly is at most three months wrong, and three months wrong is survivable.

The leaver test runs whenever anyone leaves the organization. Search the knowledge base and the estate page for the leaver's name. Every hit is a place where the document depends on a person who is no longer there. That person might be an owner, a contact, or the one who knew how the monthly job was started. Reassign each one, or mark the article outdated so the cover person knows not to trust it. Flagging beats deleting, because the outdated article still says that the problem existed and what used to fix it. QuerySolv's knowledge base, for example, has published, agents-only and draft states plus an outdated flag. That is about the minimum a solo desk needs to keep the technician's notes next to the user's answers.

A Short War Story: Two Weeks at Bluewater Bank

Tomas ran IT alone for a Bluewater Bank branch office of sixty people. Before two weeks of leave he wrote a one-page runbook and a one-page estate page. He then spent an hour walking Lena, the office manager, through both. Over the two weeks Lena handled thirty tickets from the first page and the knowledge base. When the branch's internet link dropped on the second Wednesday she found the carrier on the estate page. She quoted the circuit reference and had an engineer on site by the afternoon. The one thing that broke was the statement-printing job that ran at 06:00 on the first of the month. It depended on a mapped drive on Tomas's own workstation and was on no page anywhere. That was because Tomas had set it up in his first month and forgotten it existed. Statements went out a day late. Nobody was blamed. The job moved to a server the same week, and the estate page gained a new column headed "runs from". The documentation held everywhere it existed and failed in the one place it did not. That is the only way documentation ever fails.

I have had my own version of the mapped drive. Mine was a scheduled task on a laptop. The laptop went on leave with me.

The Estate Page and the Runbook First Page

The template below is both pages. Fill in the estate page first, because it is the one that turns an outage into a phone call. Keep both where the cover person can find them without asking. Use a folder they already have access to, or the agents-only section of the knowledge base. Do not keep them in your mailbox. Your mailbox is the one place the cover person is guaranteed not to have.

ESTATE PAGE
Organization: ____________   Maintained by: ____________   Reviewed: ________
(Review every quarter, one hour. Sort contract end dates to the top.)

System (label / hostname)   What it does      Runs on / from       Owner (business)
--------------------------  ----------------  -------------------  ----------------
________________________    ______________    _________________    ______________
________________________    ______________    _________________    ______________

Vendor and contact          Contract / warranty ends   Keys (vault entry name only)
--------------------------  -------------------------  ----------------------------
________________________    _______________________    __________________________
________________________    _______________________    __________________________

Scheduled jobs that do not run on a server, and where they run:
  ______________________________________________________________________


RUNBOOK, FIRST PAGE
Desk: ____________   Usual admin: ____________   Cover: ____________
Cover period: __________ to __________   Manager's note of authority: [ ] sent

Where tickets arrive: ____________________________________________
Look at the queue at ______ and ______. At each look, every new ticket
  gets an owner, a priority, and a reply that names the next update time.
Every reply contains: what we think it is, what we are doing, when you
  will hear from us next.
Log every walk-up and phone call as a ticket before doing anything else.

HANDS OFF (do not change; call instead)
  ______________________   call: ______________
  ______________________   call: ______________
  ______________________   call: ______________

Emergency means: ______________________________________________________
If it is an emergency: call ______________ then ______________.
If it is not: log it, reply, and it waits. That is allowed.

Can wait until I am back: ______________________________________________
Knowledge base: ____________   Estate page: ____________   Vault: ______

When you come back, ask the cover person what was missing before you ask what went wrong. The missing lines are the next version of the page. The thing that went wrong is usually one of them.

The Friday before leave will still have a quick question in it. It always does. The difference, once the three documents exist, is that the answer can be "it's on the page", and it will be.

Frequently Asked Questions