Documentation as the Sharing Medium: What to Write Down First

Tuesday, 16:20, at Harbourview Clinic. Sam leans back from his screen and asks across the desk, "Leila, how do you re-pair the check-in kiosk when it loses the printer?" Leila explains it, clearly and kindly, for the third time this year. She explains the kiosk's admin menu, the pairing code on the printer's test page, and the order that matters. Sam nods, does it, and the kiosk prints. Five weeks later a different kiosk loses a different printer and Sam, with a small private wince, asks again. Leila's explanation was good every time. It just never landed anywhere that was still there a month later.

Nothing here is anyone's fault. Spoken knowledge has a half-life of about a month in a busy head. A desk that shares by talking is a desk that re-shares the same thing on a cycle, each time costing the expert five minutes and the learner a little dignity. The explanation reached one person, once. The next technician will never hear it at all, because they were not at the desk that Tuesday, and the kiosk does not know that.

Documentation as the sharing medium means treating the written form as the way knowledge moves between people on a desk, rather than as a record made afterwards. A conversation shares with the person in the room. A document shares with everyone on the desk, the people on leave, the people not yet hired, and the person you will be in eighteen months when you have forgotten this too. This article is part of our Team Knowledge Sharing series. It sits between the rhythms, which generate the questions, and the craft of writing. Other articles in this library own that craft, and this one links them rather than repeats them.

It starts with why talking does not share and the four documents a desk shares through and the job each does. Next come the internal note as the smallest document, who should write (the learner, not the expert), and one place, visible to the desk. Then it covers what to write first, the minimum set per system, the read test, and keeping it alive inside the rhythms. A short war story and the minimum runbook set to copy finish the article.

Why Talking Does Not Share

A spoken answer has three failures that a written one does not, and they compound. The expert says it slightly differently each time, so the three people who asked have three versions. The version that was wrong about the order is the one that stuck. The learner remembers the parts they already half-understood and drops the part that was new, which was the point. And the next person, the one who joins in the autumn, never hears any version. That is because the conversation was not recorded and nobody thinks to repeat it until the kiosk breaks on their shift. The conversation at the desk is the most expensive channel the desk has, and the only one with no archive.

Talking is still the right way to answer the question in front of you; it is the wrong way to share the answer. The expert should explain the kiosk to Sam on Tuesday, because Sam needs the kiosk working and the patient is standing at it. What changes is the minute after: the answer goes somewhere that is still there in five weeks. The order that matters is written down once, in words the next person can search for. A desk that does this for a year stops having the same conversations and starts having new ones, which is the only way the conversations ever get more interesting.

The written form also survives the thing talking cannot: the expert leaving. Every spoken answer Leila has ever given is in heads that will forget it. The day she goes, the clinic's knowledge of its kiosks goes with her unless some of it has been written. This series ends with an article on that day. The whole of this one is about making that day smaller. It is about moving things out of the one head and onto a page while the head is still in the building and available to be asked what it meant.

The Four Documents and the Job Each Does

A desk shares through four kinds of document, each with a different job. The mistake most desks make is to write only one kind and expect it to do all four. The runbook is a procedure written so that a competent stranger can run it alone and know whether it worked. It shares how to do a thing. The known-error record is the recognition test and the tested workaround for a symptom that keeps coming back. It shares how to spot a thing and get round it. The internal note is the line on the ticket, visible to the desk and not the requester, that says how this ticket was actually fixed. It shares what happened here. The how-I-fixed-it article is the note promoted into the knowledge base when a second ticket needed the same answer. It shares the answer with whoever searches for it next. Four jobs, four forms, and a desk needs all four because the knowledge arrives in four different shapes.

Each of those four has an article in this library that teaches how to write it well. This article does not try to. The links in the table are where the craft lives. What this article adds is the sharing view. It covers which document moves which kind of knowledge and in what order they get written. It also covers what the minimum is for a system before the desk can call it shared. Read the craft articles when you are writing. Read this one when you are deciding what to write.

The Internal Note Is the Smallest Document

Everything shareable starts as a note on the ticket, which is why the note is the document to get right first. A note that says "fixed" shares nothing; it is a status with a verb. A note that says "kiosk had dropped the printer pairing; re-paired from the kiosk admin menu using the code on the printer's test page; printer must be powered on before the kiosk is, or the pairing drops again" is a document. It is already shared because the next technician who searches the tickets for "kiosk" and "printer" will find it in the ticket where it happened. The difference between the two notes is ninety seconds, written while the fix is fresh. The second one is the raw material for everything else in this article.

The note belongs on the ticket and nowhere else first, because the ticket is where the next person will look. In QuerySolv the internal note sits on the ticket beside the public reply, invisible to the requester. The ticket's complete event history keeps it with everything else that happened. In any tool, the point is the same, that the how lives with the what. A fix written in a personal notebook, a chat message, or the expert's memory is a fix that has been recorded somewhere the next person will not search. The note is a document precisely because it is attached to the thing it describes.

Documents are promoted by reuse, and the note is the bottom of the ladder. The first time a fix is needed, it is a note on the ticket. The second time, the technician who finds the note copies it into a short knowledge base article, because two tickets is a pattern. The third time, the article becomes a known-error record, with its recognition test, if both conditions are met. The symptom is recognisable on sight, and the fix is a workaround rather than a cure. If the fix is a procedure with steps and checks that a stranger must be able to follow at night, it becomes a runbook. Nobody decides in advance which rung a piece of knowledge will reach. The tickets decide, and the desk's only job is to write the note that makes the climb possible.

Who Writes: The Learner, Not the Expert

The person who should write the document is the one who has just learned the thing, not the one who has always known it. This is the most useful rule in the article. The expert cannot see what is obvious, because obvious is the name for what the expert stopped noticing years ago. An expert's runbook is a list of the steps they would have remembered to mention. The learner knows exactly what they did not know ten minutes ago. They know that the printer must be on first and that the pairing code is on the second page of the test print. They know that "admin menu" means holding the corner of the screen. Those are the lines a third person will need, and only the learner can still see them.

This is why the weekly half hour in the cross-training article of this series ends with five minutes of the learner writing. The learner writes what they could not follow. The expert reads it and corrects what is wrong. The document is better than either could have written alone, and it took five minutes because the knowledge was still warm. A runbook written by the second person who learned a system is the one a third person can follow. A runbook written by the first is a memoir.

I know this because I wrote runbooks for years that only I could follow. I was mildly puzzled each time a colleague phoned me from the server room with the runbook open. They were accurate. They were complete, in the sense that every step I would have taken was in them. They were useless to anyone who did not already know which of the two consoles I meant. I did not know I had two consoles in my head until someone who had just learned the system wrote the runbook instead, and put the console's name in step one.

One Place, Visible to the Desk

Documents share only from the place the desk already looks, and there must be one such place, not four. For most desks it is the internal section of the knowledge base, the same search that finds the user-facing articles, with the technicians' documents marked so that a user never sees them. For a desk without one, it is a single shared folder with one file per document, named by the symptom in the words a ticket would use. The test is not whether the document exists. It is whether a technician who has never seen the kiosk finds its runbook, from the words in the ticket, in under a minute, without asking anyone. If the answer is "it's in Leila's folder", the answer is no.

Keep the technicians' documents out of the users' sight, and the sharing gets easier, because the writer can be plain. A runbook that says "the pairing fails silently if the printer's firmware is old; the clinic has three old ones at reception" is a sentence for the desk, not for the receptionist. A desk that knows its internal documents are internal writes that sentence. If you run QuerySolv, a knowledge base article can be visible to agents only or to everyone. In QuerySolv, the runbook goes in the first kind while the patient-facing "what to do if the kiosk will not print your ticket" goes in the second. Most tools have some version of the split. The discipline is to use it, so that nothing shareable is held back out of worry about who might read it.

A solo administrator has the same problem in a sharper form, because the one place is the only colleague they have. The document on a one-person desk is the second person: the thing that knows what you knew on the day you cannot be reached. That is the argument of Documentation as Your Second Person. A five-person desk is a one-person desk five times over for every system with a bus factor of one, and the same argument applies to each row.

What to Write First: The Minimum Set

For each system with a bus factor of one, write four short documents before anything else. Call the system "documented" only when all four exist and a second person has used them. First comes the where-things-are card: one page naming the server, the service, the console, and the account used to administer it. It also names the vendor and the contract reference, where the password is kept (never the password itself), and who to call. Second, the first-aid runbook: the restart or the single most common recovery, with checks and expected output. Third, the commonest failure, as a known-error record: how to recognise it and the tested way round. Fourth, the scheduled job, if the system has one: the monthly export, the annual renewal, with the date it is due and what "done" looks like. That is the minimum set, and it is the documentation half of fixing a single point of failure.

The where-things-are card comes first because it is the document most often missing and the cheapest to write. The night the kiosk server fails, the stranger does not need the architecture. They need to know which server, what the service is called, which account signs in, and where the password lives. Those four facts take ten minutes to write and are the difference between a ten-minute fix and a two-hour search. Most desks skip the card because the expert has never needed it, which is the same reason the expert has never needed any of this.

Do not start with the architecture document, the one with the diagram and the history and the reasons. Every expert wants to write it, because it is the document that shows how much they understand. It is the document a stranger at night will never read. Write the four short ones, let a second person use them, and then write the architecture document if there is a quiet month, which there will not be. The audit at the start of this series ranks the systems. Within a system, the minimum set ranks the documents. The ranking is by how often a stranger will need each one, not by how interesting it was to write.

The Read Test

A document is finished when a second person has used it to do the thing without asking the author, and not before. This is the same standard the bus-factor grid uses for a cell, and for the same reason. The author cannot tell whether their document works, because the author fills every gap in it without noticing. The half hour is the test bed. The learner opens the runbook, and the expert keeps their hands in their pockets. Every place the learner stops and looks up is a line the document was missing. Fix those lines the same day. A runbook that has survived one learner is a runbook; one that has survived three is a good one.

Put a "last used" line at the bottom of every runbook and known-error record, with the date, the person and the ticket. That is because that line is the document's claim to be true. A procedure nobody has run in a year is a hypothesis about a system that has had a year of changes. The read test and the last-used line turn the knowledge base from a library of things people once knew into a record of things people can currently do. That is the only kind of knowledge base that shares anything on a bad day.

Keeping It Alive Inside the Rhythms

Documentation stays alive when every rhythm the desk already runs either reads a document or writes one. Documentation dies when writing is a separate activity with its own day. The half hour reads a runbook and writes its corrections. The ticket swap writes internal notes, the expert's on what they would have done differently and the learner's on what they did. The shadow day writes the list of things the expert touched that nobody had written down. The teach-back reveals the document that does not exist yet, because the learner cannot explain a thing they have only ever followed. The huddle reviews the known-error list once a week and asks which record is out of date. None of those is a documentation task. All of them produce documentation.

The documentation day never comes, and a desk that waits for it has decided not to document. The reasons are in the capture series, and they are the reasons you already know. The day is cancelled by the first incident. The knowledge has gone cold by the time it arrives. The person who was going to write everything up has left. The alternative is a desk that writes a little every day, inside the work, at the moment the knowledge is warm. Ninety seconds on a note, five minutes at the end of a half hour, ten minutes for a where-things-are card. A desk that does that for a year has a knowledge base that shares. A desk that booked a documentation day has a calendar entry that was moved.

A Short War Story: The Till Procedure at Northgate Retail

Northgate Retail's desk supported the tills in eleven stores. Grace, who had set them up, wrote a thorough and accurate document on bringing a store's tills back after a network failure. It included the order of the steps, the one setting that had to be changed on the back-office machine first, and the vendor's support reference. She wrote it in her own documents folder, because that was where she wrote things, and told the desk it existed. On a Saturday morning in her second week of leave the flagship store lost its network. The tills came back without the back-office setting. The three technicians on the desk spent the morning trying things from memory while the store took cash and wrote receipts by hand. That was because none of them could find the document and Grace's folder was Grace's. The procedure was found two months later by the technician clearing Grace's account after she left for another job. It was still correct, and had been the whole time. The review put the cost at a morning of a flagship store on paper, three technicians' Saturday, and a weekend of reconciling hand-written receipts. A document shares nothing from a personal drive; the place is as much the medium as the page.

The Minimum Runbook Set

The template below is the minimum set for one system, on one page, as plain text. Copy it once per system with a bus factor of one, starting with the three the audit chose. The learner fills it in during the half hours. The expert corrects. The "used by a second person" line is what lets the system be called documented. Nothing in it is a password. The card says where the password is kept, and the keeping is done by whatever the desk already uses for secrets.

MINIMUM RUNBOOK SET — ONE SYSTEM
System: ______________________   Only owner today: ________   Learner writing: ________
Where these live: ______________________ (one place, visible to the desk only)

1. WHERE-THINGS-ARE CARD            Status: [ ] drafted  [ ] corrected  [ ] used by a second person on ______
   Server(s) and their names:  _____________________________________________________
   Service name(s):             _____________________________________________________
   Console or admin page:       _____________________________________________________
   Admin account used:          ____________   Password kept in: _______________ (never here)
   Vendor:  __________________  Support line: ______________  Contract ref: __________
   Who to call on the desk:     ____________   Then: ____________
   Depends on:                  _____________________________________________________

2. FIRST-AID RUNBOOK               Status: [ ] drafted  [ ] corrected  [ ] used by a second person on ______
   Title (symptom, in the ticket's words): _________________________________________
   Applies when: ________________________________   Not this if: ______________________
   Steps, each with a check and the expected result:
     1. _______________________________  Expect: ___________________________________
     2. _______________________________  Expect: ___________________________________
     3. _______________________________  Expect: ___________________________________
   Rollback: ______________________________________________________________________
   Stop after ____ minutes and call: ____________   Send: steps run, what each check showed
   Last used: ________ by ________ on ticket ________

3. COMMONEST FAILURE (known error)  Status: [ ] drafted  [ ] corrected  [ ] used by a second person on ______
   Symptom: ______________________________________________________________________
   How to recognise it: ___________________________________________________________
   Workaround (tested on ______): __________________________________________________
   What it does not fix: ___________________________________________________________
   KE number if the desk uses one: ________

4. SCHEDULED JOB (if any)           Status: [ ] drafted  [ ] corrected  [ ] used by a second person on ______
   Job: ______________________   Runs: [ ] monthly  [ ] quarterly  [ ] yearly   Due: ________
   Where it runs: ______________   How to run it by hand: ________________________________
   What "done" looks like: ________________________________________________________
   Who notices if it fails: ____________   By when: ________

SYSTEM COUNTS AS DOCUMENTED WHEN all four are "used by a second person".  Date reached: ________

Frequently Asked Questions