atelier/domains/documentation/doc-templates.md

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