Who
What Knowing It Makes You Leave Out
Pages written by the person who knows most are accurate and incomplete in a specific, predictable way, and the gaps are invisible to their author.
What nobody wrote down here, and what it cost
What the deploy order is
Known by one person who is in meetings
Asked rather than written, nine times
Why the import runs twice
Known by somebody who left in March
Nobody now knows, and it is asked at every incident
two things nobody wrote down · 14 occasions it cost somebody something
Two things, fourteen occasions, and one of them is now unknowable.
Where the real question is capacity rather than willingness, the official page can supply the work-pattern evidence that a documentation discussion otherwise lacks.
For additional context beyond this collection, see the resources maintained by G2.
Five gaps found in pages that had already been written, with what the author had assumed
Which environment the commands run in
Run in the wrong one, twice by the same person
The author had never run them anywhere else
That the first step requires an approval
Blocked at step one and asked
The author had the approval permanently and had forgotten it existed
What the output looks like when it works
Asked whether it had worked
The author recognised success instantly and never thought to describe it
That two of the steps can be done in any order
Done strictly in sequence, slowly
The author did them in a habitual order and wrote that order down
What to do when step four fails
Asked, every time
The author had never seen step four fail
five things nobody wrote down · 20 occasions it cost somebody something
Five gaps in pages that existed, twenty occasions they cost somebody something. None of these is an error: every page was accurate. They are the places where an author's knowledge supplied something silently, and the reader had nothing to supply it from. One team's own quarter, collected from the questions asked about existing pages.
A page written by the person who knows a thing best is accurate. It is also, reliably, missing a particular class of information, and the author cannot see which.
This is not carelessness. It is what expertise does to a description.
What gets silently supplied
When somebody who knows a process writes it down, their knowledge fills in several things between the sentences without their noticing.
Where it happens. Which machine, which environment, which account.
What state the world is in beforehand. What must already be true for step one to work.
What success looks like. The author recognises it instantly and therefore never describes it.
What to do when it goes wrong. If the author has never seen it fail, the failure case does not occur to them as a thing to cover.
Which parts are order-dependent. Habitual order and required order feel identical from inside.
Why the author cannot find these
Reading your own page does not help, because reading it triggers the same knowledge that wrote it. You supply the missing context automatically, the page reads as complete, and it is complete — for you.
This is the reason that proofreading your own documentation has almost no yield and is the main thing people try.
I read it three times and it was fine. The first person to use it ran the whole thing on the wrong machine, and the page does not say which machine, and I cannot now see how I would have known to say it.
The only reliable detector
Somebody who does not know the subject attempts to use the page, in front of you, without being allowed to ask.
Every place they stop is a gap. Every place they guess is a gap. Every question they would have asked, if permitted, is a gap.
Twenty minutes of this finds more than any amount of re-reading, and it finds the specific things in the list above rather than the typos that proofreading finds.
The rule about not asking is the part people drop, and dropping it destroys the method: a question answered out loud fills the gap in the room and leaves it in the page.
Doing it cheaply
The full version needs two people and twenty minutes. There are smaller versions worth having.
Give the page to somebody and ask them to mark every point at which they were unsure, without telling you what the uncertainty was. The marks alone locate the gaps.
Or ask one question of a non-expert reader: what would you do first? If the answer is not the first step, something before step one is missing.
Or add, as a habit, the four sentences that cover the list above: where it runs, what must be true first, what success looks like, what to do if it fails. Those four cover most of what gets supplied silently.
The four sentences
Worth stating as a checklist because they are mechanical and they work without anybody having to notice their own assumptions.
- This runs on X, as user Y.
- Before starting, Z must already be true.
- When it has worked, you will see W.
- If step N fails, do V — or ask A, because this has not happened before.
Of the four, the last gets left out most and costs the most by its absence: a reader who is stuck with no stated failure case cannot tell whether they have broken something.
Why this argues for the non-expert author
Everything here is an argument for the arrangement described two pages earlier: the expert talks and somebody else writes.
A non-expert writing from an explanation cannot silently supply the context, because they do not have it. They have to ask where it runs, and what must be true first, and how you know it worked — which is why their version contains those things and the expert's does not.
The resulting page is usually less elegant and substantially more usable.
Running the check cheaply
The full version is somebody attempting the page in front of you without asking. Where that cannot be arranged, three smaller versions find most of it.
- Give it to somebody and ask them to mark every point where they were unsure — not what the uncertainty was, just where.
- Ask one question: what would you do first? If the answer is not step one, something before step one is missing.
- Read it aloud to somebody who does not know the subject, and watch their face rather than the page.
Each takes under ten minutes. All three beat re-reading it yourself, which finds typos and nothing else, and which is what almost everybody does instead.
The page that is accurate and useless
The end state of unchecked expert writing is a document that is correct in every statement and cannot be followed by anybody.
It tends to be defended, reasonably, on the grounds that everything in it is true. That defence is sound and beside the point: the question is not whether the page contains errors but whether somebody who does not already know can get to the end of it.
That question has one way of being answered, and it involves watching somebody try.