Jon Chery
1.1 KiB
Documentation — First Principles
1. The Principles
P1. Documentation is Code
It is versioned, reviewed, tested, and owned. Unowned docs rot.
P2. Audience Awareness
Different readers need different docs. A new user, an operator, and a contributor are different audiences.
P3. Examples are Mandatory
Code without examples is incomplete. Show, then explain.
P4. Currency
Docs that lie are worse than no docs. Stale docs are technical debt.
P5. Discoverability
The right doc is findable in under a minute. Structure, search, and indexing are part of the doc.
P6. Conciseness
Say what is needed, no more. Verbose docs are skimmed, then ignored.
P7. Structure
Consistent structure aids scanning. Headings, ordering, and formatting follow conventions.
P8. Why Over What
Document intent, decisions, and tradeoffs. The "what" is in the code.
P9. Living Documents
Docs evolve with code, not after. Doc PRs ship with code PRs.
P10. Public by Default
If it is not documented, it does not exist. The absence of docs is a feature gap.