| # Documentation Taxonomy |
|
|
| Where to put new documentation. Inspired by [Diataxis](https://diataxis.fr/) but adapted for agentic engineering where both humans and AI agents consume docs. |
|
|
| ## Decision Tree |
|
|
| ``` |
| "I need to write something down." |
| │ |
| ├── Does it tell someone HOW TO do a specific task? |
| │ └── YES → docs/guides/ [how-to] |
| │ |
| ├── Does it describe WHAT something IS (APIs, interfaces, facts)? |
| │ └── YES → docs/references/ [reference] |
| │ or → docs/ARCHITECTURE.md [reference] |
| │ or → docs/delivery-specs/ [reference] |
| │ |
| ├── Does it explain WHY a decision was made? |
| │ └── YES → docs/design-docs/ [explanation] |
| │ or → vision/ [explanation] |
| │ |
| ├── Does it validate WHETHER we should build something? |
| │ └── YES → docs/discovery/ [explanation] |
| │ |
| ├── Is it a durable pattern extracted from work? |
| │ └── YES → docs/learnings/<category>.md [reference] |
| │ |
| ├── Is it an idea, investigation, or scratchpad? |
| │ └── YES → docs/exploration/ [exploration] |
| │ |
| └── Is it tracking active work progress? |
| └── YES → docs/exec-plans/ [how-to] |
| ``` |
|
|
| ## Directory Purpose Map |
|
|
| | Directory | Diataxis Type | Audience | Created By | Mutability | |
| |-----------|--------------|----------|------------|------------| |
| | `docs/guides/` | How-to | Humans + Agents | Manual or extracted | Stable | |
| | `docs/design-docs/` | Explanation | Humans + Agents | `design-doc` skill | Append-only (decisions are permanent) | |
| | `docs/discovery/` | Explanation | Humans (agents read) | `discovery` skill | Per-feature, stable once validated | |
| | `docs/delivery-specs/` | Reference | Agents + Humans | `delivery-spec` skill | Stable once approved | |
| | `docs/references/` | Reference | Agents | Manual or generated | Updated as needed | |
| | `docs/learnings/` | Reference | Agents + Humans | `compound-engineer` | Append-only (budgeted) | |
| | `docs/exploration/` | Exploration | Humans only | Manual | Ephemeral -- graduate or archive | |
| | `docs/exec-plans/` | How-to | Humans (agents read) | Manual | Active then archived | |
| | `vision/` | Explanation | Humans + Agents | `strategy` skill or manual | Rare changes | |
| | `specs/` | Reference | Agents | Autocode skills | Per-feature lifecycle | |
|
|
| ## Self-Organization Rules |
|
|
| 1. **Start minimal.** Don't create directories until you have content for them. Skills create directories on-demand. |
| 2. **Graduate content.** Exploration docs that prove durable should move to the appropriate permanent location (learnings, guides, references). |
| 3. **One purpose per doc.** If a document is doing two things (e.g., explaining WHY and telling HOW), split it. |
| 4. **Agents navigate by maps.** Keep `AGENTS.md` as a pure index. Keep `docs/README.md` as the docs index. Don't inline content in indexes. |
| 5. **Enforce mechanically.** Use `DOCS_CONTRACT.json` and `opencode-ctx docs validate` to prevent drift. Narrative instructions degrade with context length; lints apply everywhere. |
|
|
| ## Sources |
|
|
| - [Diataxis](https://diataxis.fr/) -- Four-type documentation framework (Daniele Procida) |
| - [Cynefin](https://en.wikipedia.org/wiki/Cynefin_framework) -- Complex vs. ordered domains inform when to prescribe vs. let emerge (Dave Snowden) |
| - [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/) -- "Give Codex a map, not a 1,000-page instruction manual" |
|
|
