Note
Documentation
Documentation is where a product explains its world: not only the steps, but the model that makes the steps make sense.
-
01
Orient
Show where the reader is and what this page will help them do.
-
02
Demonstrate
Offer a complete path with realistic, working examples.
-
03
Explain
Reveal the mental model, tradeoffs, and neighboring concepts.
Documentation is an interface
The reader arrives with a task, incomplete context, and limited attention. Documentation must help them locate themselves before it can teach them anything. Titles, navigation, examples, and warnings are interaction design.
A page succeeds when the reader knows both what to do now and where to look when the situation changes.
Examples carry the truth
Abstract explanation feels safe because it avoids committing to a real case. Working examples are more demanding. They expose missing steps, awkward names, hidden dependencies, and assumptions the product team forgot it was making.
That is why examples are not decoration. They are a form of product testing performed in public.
Explain the model
A recipe can get someone through one task. A mental model helps them solve the next task without returning to the beginning. Good documentation moves between both levels: concrete enough to act on, conceptual enough to transfer.
The reader should leave with a more accurate picture of how the system behaves, including where that picture stops being complete.
Maintenance is part of authorship
Outdated documentation is dangerous because it still looks authoritative. Every product change creates a documentation question, whether or not the team chooses to answer it.
Treating documentation as part of the product means giving it ownership, review, and the same respect for correctness as code. Clear words cannot rescue a page that no longer tells the truth.