# 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.