File size: 3,657 Bytes
9e64e71 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | # 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"
|