Jon Chery
37 lines
1.1 KiB
Markdown
37 lines
1.1 KiB
Markdown
# 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. |