Jon Chery
83 lines
2.2 KiB
Markdown
83 lines
2.2 KiB
Markdown
# Doc Templates — Derived Rules
|
|
|
|
> Derives from `domains/documentation/first-principles.md` P7 (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 | |