Somebody asks why the service retries three times instead of five. You know the answer is written down. You do not know whether it is in the design doc, the onboarding page, a comment on a ticket, or a message from eighteen months ago, and finding out will take longer than working it out again.
That is the actual failure mode of documentation, and it is not staleness. A stale document is at least findable. This one is fine, correct, and unlocatable, because nothing about the way it is stored says what it is for.
Five documents, five questions
The fix that has held up for me is embarrassingly simple: give each kind of document exactly one question, and put it where that kind lives.
| the question it answers | mutable? | |
|---|---|---|
| product requirements | what are we building, and for whom | yes, until it ships |
| user journey | what does a person do, start to finish | yes |
| feature states | what does this screen do in every state | yes |
| decision record | why is it built this way, and what did we reject | never |
| lexicon | how did we solve this before | append only |
The mutability column is doing more work than it looks. A document that can be edited is a document whose history you do not have, and for four of these that is fine. For the fifth it is the whole point.
The three that get no document
This is the part teams find surprising, and it is the part that keeps the folder small enough to trust.
The API shape does not get a document. There is a schema file, both sides are generated from it, and a prose description would be a second source of truth that nothing checks. The architecture rules do not get a document either: there is a test, and it fails. The conventions an assistant needs on every turn live in the always-on context file, which is the only file with a price per turn, so anything look-up-able goes in a registry instead.
The rule generalises. If something is executable, describing it in prose creates a second version that will disagree with the first, and the one nobody runs is the one that will be wrong.
The order they get written in
requirements why this is worth building, and what done means for a user
-> journey what the person actually does, step by step
-> states what each screen shows, including the bad ones
-> issue one implementable unit, with numbered requirements
-> decision written when a choice closed off alternatives
Only the issue is what somebody, or something, implements. The rest exist so the issue can be written well enough to be implementable, which is where most of the failure actually happens: a competent implementation of an ambiguous ticket is the most expensive thing a team can produce.
The decision record comes last on purpose. You cannot write it before the decision, and writing it during the argument produces advocacy rather than a record.
Why this got sharper recently
Two people onboarding a year apart used to be the whole audience for this. It is not any more, and the second reader has different economics.
A person who cannot find the retry decision loses twenty minutes, once. An assistant that cannot find it re-derives it from scratch on every task, forever, and produces something plausible each time. The cost of unlocatable documentation stopped being a one-off and became a subscription.
That is also why the folder having a README explaining which file answers which
question is worth more than any individual file in it. It is the only page that
tells a stranger, human or otherwise, where to start.
If your team writes documentation nobody can find, that’s the work I do.