Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
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.