Why not
The Thing You Know Too Well to See
The things most worth writing down are the ones that feel too obvious to write, and they feel that way only to the people able to write them.
What nobody wrote down here, and what it cost
How the staging database is rebuilt
Asked of the same person seven times
Four minutes each, plus the interruption
What the deploy order is
Guessed, then corrected by whoever noticed
Wrong on the ninth occasion
Why the retry limit is three
Re-argued at two planning meetings
The reasoning was in nobody's head
three things nobody wrote down · 20 occasions it cost somebody something
Three things, twenty occasions, and one customer who noticed.
Before adding another required page, managers can the software overview and check whether the underlying bottleneck is missing knowledge, overloaded authors, or unclear ownership.
The broader workflow can also be checked against guidance from Hootsuite.
Six things a team never wrote down because everybody who could write them found them obvious
That the import must run before the reconciliation
Asked, or discovered the hard way
Obvious to three people and to nobody else
That the staging credentials rotate monthly
Found out when something stopped working
Nobody could remember learning it
That the client's week starts on Sunday
Two reports went out on the wrong day
Known by the account manager and assumed to be general knowledge
That the build needs a clean checkout
Twenty minutes each time
The person who knew described it as not worth a page
Which of the two dashboards is authoritative
Asked in the support channel
Both existed, one was stale, everybody senior knew which
That deployments pause during month-end
One deployment went out anyway
Written nowhere, observed by everybody who had been there a year
six things nobody wrote down · 27 occasions it cost somebody something
Six things, twenty-seven occasions. Every one was described by somebody as too obvious to be worth writing. Each was obvious only to the people who already knew it, which is the definition of the problem rather than an argument against the page. One team's own quarter.
Each person on a team carries a set of facts they would not think to state, because stating them feels like announcing that water is wet.
Those facts are, with remarkable consistency, the ones that cost other people the most.
Why the overlap is so exact
The feeling that something is too obvious to write is a feeling about your own knowledge, not about the fact.
It arrives once a thing has been known long enough to stop feeling like information. At that point it is part of how the world looks, and describing it feels like describing the furniture.
The people for whom it is not obvious are, by definition, not the people who would write it. So the fact sits in the one place where nobody can see that it needs writing: inside the head of somebody for whom it is no longer a fact at all.
The shape of these things
They are nearly always short. Most of them are one sentence. The import runs before the reconciliation; the credentials rotate monthly; that dashboard is the stale one.
They are nearly always ordering or precedence. What must happen before what, which of two things is authoritative, when something does not apply.
And they are nearly always discovered by newcomers through failure rather than through asking, because they do not know enough to form the question. You cannot ask which dashboard is authoritative if you do not know there are two.
How to find them
Three methods, in descending order of how well they work.
Watch what people ask. A question asked twice by different people is a candidate; asked three times it is not a candidate, it is an answer waiting to be written down.
Watch what goes wrong in a small way. Near-misses and twenty-minute confusions are the surface signal of an unwritten precedence. The thing to record is not the incident but the fact that would have prevented it.
Ask the newest person what surprised them in their first month, while they can still remember. This window is short — about six weeks — and it closes permanently. After that they have the same blindness as everybody else, and it is nobody's fault.
The objection, and what is wrong with it
The objection to writing these down is that a document full of obvious statements is condescending and nobody will read it.
The first half is a real risk and is solved by where the thing lives rather than by not writing it. A sentence next to the thing it is about — in the runbook, in the script, in the channel description — reads as a note. The same sentence in a general document called Important Facts reads as a lecture.
The second half is mistaken. These are not read front to back by anybody; they are found by somebody with a specific confusion at a specific moment, which is exactly when a one-line fact is worth the most.
The six-week window
The most valuable documentation asset a team has is the person who joined five weeks ago, and almost nobody uses it.
They can still see the shape of the place. They remember which things confused them and which answers they had to extract from somebody. They have not yet acquired the blindness. And they are usually keen to be useful in a way that does not require knowing anything.
Asking them to write down what surprised them is a task they can actually do, that nobody else can do, that takes an hour, and that produces exactly the class of fact this page is about.
It is also, incidentally, the one documentation task where the person best placed to do it is not the person with the least time.
Where these facts should live
A sentence stating something obvious reads very differently depending on where it is put, and the location is the whole difference between a note and a lecture.
- Next to the thing it describes: in the runbook, the script, the channel topic.
- In the error message or the comment, where somebody will hit it.
- At the top of the page about the process it constrains.
- Not in a general document of important facts, which nobody opens.
The test is whether somebody with the confusion will encounter the sentence without having decided to look for it. Obvious facts are never sought deliberately, because the person who needs one does not know it exists.
What this does not cover
Not everything unwritten is unwritten because it is obvious. Plenty of it is unwritten because it is genuinely hard to write, or because writing it would require settling something, or because nobody has forty minutes.
This page is about the subset that is easy, short, and invisible to everybody who could do it — which is a large subset, and the cheapest one to fix.