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.
2.2 KiB
2.2 KiB
Doc Templates — Derived Rules
Derives from
domains/documentation/first-principles.mdP7 (Structure), P2 (Audience Awareness), P3 (Examples are Mandatory).
Document Structure (P7)
Every framework document follows a consistent structure:
# <Title>
> One-line purpose. Who reads this and when.
## 1. Manifesto (or Introduction)
Why this document exists. The core belief.
## 2. The Principles (or Rules)
The numbered, named, derivable rules. Each rule has:
- A name (P1, P2, ...)
- A one-line definition
- A "what it means" paragraph
- A "what violates it" entry
## 3. Conflict Resolution (for first-principles docs)
Precedence among the rules. Non-tradeable declarations.
## 4. What Violates These Principles
A table of violations and the principle they breach.
## 5. Relationship to Core
Derivation link. See `matrix/principles-matrix.md`.
- The structure is the contract. A reader can scan any framework doc and find the same sections.
- Derived (topic) docs simplify: drop §3, replace §5 with "Derives from
<domain>/first-principles.md."
Audience Templates (P2)
For Agents
- Lead with what to check before completing a task.
- Bullet lists, not paragraphs.
- "Run this checklist" framing.
For Humans (Onboarding)
- Lead with what this is and who it's for.
- Reading order. Quickstart.
- Conversational tone, not terse.
For Humans (Reference)
- Lead with the rules, indexed.
- Tables for lookup.
- Cross-references to other docs.
Example Template (P3 Examples are Mandatory)
Every rule includes an example. The template:
### P<n>. <Name>
<one-line definition>
<what it means>
Good:
<example>
Bad:
<counter-example> (violates P<n>)
- The "good" example is realistic, not a strawman.
- The "bad" example cites the principle it violates.
- Examples are code, not prose. Show, don't tell.
What Violates Doc Templates
| Violation | Principle |
|---|---|
| A doc with no examples | P3 Examples are Mandatory |
| A first-principles doc with no "what violates" table | P7 Structure |
| A doc that does not link to its core derivation | P5 Discoverability |
| Inconsistent structure across domain docs | P7 |
| A doc with no audience statement | P2 Audience Awareness |