Who
Writing About Somebody Else's Work
People hesitate to document work that is not theirs. The hesitation leaves a large, easily filled gap: the owner is usually relieved rather than offended.
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.
A useful operational baseline is to compare the writing burden with real work patterns; view the tool shows one practical way to make that comparison without relying on memory.
For a separate specialist reference on publishing and digital practice, consult Product Hunt.
Four things that stayed unwritten because the obvious author was not the owner
How the pricing service decides tiers
Asked of the owning team every time
A neighbouring engineer understood it and did not feel entitled to write it
What the shared library's retry behaviour is
Read from the source, by four people separately
Nobody felt it was theirs to describe
How the finance export is reconciled
Explained verbally by the same person
An engineer who had watched it twice could have written it
What the support escalation path is
Asked in the support channel
Everybody assumed somebody in support would write it
four things nobody wrote down · 18 occasions it cost somebody something
Four things, eighteen occasions. In each case somebody who was not the owner could have written a usable page and did not, because writing about another person's work feels like an intrusion. It is a cheap intrusion and the owner is almost always glad of it. One team's own quarter.
A good deal of what nobody writes down is held by one team and needed by another. Somebody in the second team understands it well enough to write a usable page, and does not, because it is not theirs.
The hesitation is social rather than practical, and it costs more than it protects.
What the hesitation is about
Three worries, and they are all reasonable in form.
Getting it wrong in public, about somebody else's area, where being corrected is more exposed than usual.
Appearing to criticise. A page about somebody else's system can read as an observation that they failed to write one, whether or not anybody intends it.
Overstepping. Describing how another team's thing works looks, from some angles, like claiming authority over it.
None of these is imaginary. All three are much smaller than they feel, and all three are dissolved by one sentence.
The sentence
"I wrote up what I understood about X so our team stops asking you — can you check it?"
It converts every one of the three worries into its opposite. Getting it wrong is expected and the check is the point. It is not criticism because it is framed as reducing a burden. It is not overstepping because the owner is being asked to confirm.
In practice the response is nearly always relief. The owner has been answering the same question for months, has not had an hour to write it, and is now being handed a draft.
What the outside author can actually write
More than they think, and less than everything.
They can write what it does, from the outside: the interface, the behaviour, what to expect. This is frequently the only part their own team needs.
They can write how to use it, including the practical details the owner has stopped seeing.
They can write what they asked and what they were told, which is a legitimate document in itself.
They cannot write why it is that way, and should not try. Reasons belong to the owner, and an outsider's guess at a reason is the one thing in this arrangement that does real damage.
Marking the boundary in the page
The page should say what it is. One line at the top:
Written from outside the team that owns this, from what they told us. Accurate as far as we know; the reasoning behind the design is not described here.
That line does three jobs: it sets the reader's expectations, it protects the owner from being held to somebody else's description, and it makes the page easy to approve because nobody is claiming more than they have.
When the owner does not respond
Common, and not usually a refusal. The check request lands in a busy week and does not come back.
The workable default: publish it with the line above plus the date you asked, and say that corrections are welcome. An unchecked page clearly labelled as unchecked is better than no page, and it has the useful property of being the fastest way to obtain a correction from a busy person, who will find an error much more quickly than they would find an hour.
What is not acceptable is publishing it as though it were authoritative.
The reverse case
The same logic runs the other way: if somebody outside your team writes about your work, the correct response is thanks and corrections, not objection.
It is worth saying this explicitly once, because the default reaction to discovering a page about your system written by somebody else is a small flare of territoriality, and that reaction is what teaches the next person not to bother.
Where this is most valuable
At the seams. Nearly all of the questions that cross between teams are about interfaces and behaviour rather than internals, which is exactly what an outside author can write.
Seams are also the places least likely to be documented by anybody, because each side considers them the other's responsibility, and the cost of the absence is paid in cross-team questions that are slow for everybody.
What an outsider can and cannot write
The boundary is not about seniority or permission. It is about which statements an outsider is actually in a position to make.
| Can write | Cannot write |
|---|---|
| What it does, from outside | Why it is that way |
| How to use it | What was tried and rejected |
| What you asked and were told | What is coming next |
| What surprised you about it | What must not be changed, and why |
The right-hand column belongs to the owner and an outsider's guess at any of it does real damage, because a plausible wrong reason is harder to dislodge than no reason at all.
What it does not replace
An outside page does not remove the need for the owner to write the parts only they can write. It covers the usage layer, which is the layer most asked about.
It is also not a way of avoiding the conversation about who owns the documentation of a shared thing. That conversation is worth having. This is what to do in the two years before anybody has it.