Skip to content

DR-004: Adopt Diataxis Framework for Documentation Organization

Home › Reference › Decision Records › Dr004

Status

  • [x] Accepted
  • [ ] Proposed
  • [ ] Rejected
  • [ ] Deprecated
  • [ ] Superseded

Date: 2025-11-03

Context

Docs need to serve different user intents: learning, solving problems, understanding concepts, looking up details. Traditional flat/component-based structures don't map to these needs.

Problem: How to organize docs for different user needs with consistency and discoverability?

Decision

Diataxis framework with four categories:

  1. Tutorials (docs/tutorials/): Learning-oriented, step-by-step, little prior knowledge
  2. How-To Guides (docs/how-to-guides/): Problem-oriented, single task, actionable steps
  3. Explanation (docs/explanation/): Understanding-oriented, concepts, context, design
  4. Reference (docs/reference/): Information-oriented, precise, comprehensive (e.g., specifications/, decision-records/)

Structure:

docs/
├── tutorials/
├── how-to-guides/
├── explanation/
├── reference/
└── templates/

Consequences

Positive: Clear intent mapping, no duplication, category-specific quality, predictable structure, scalable, industry standard

Negative: Learning curve, navigation overhead, migration effort

Alternatives Considered

  1. Flat Structure: Rejected - hard to navigate, no learning path, scales poorly
  2. Component-Based: Rejected - duplicates patterns, no intent guidance, mixes types
  3. README-Heavy: Rejected - files become long, inconsistent, poor cross-referencing
  4. Wiki-Style: Rejected - no structure, disorganized, hard to review, separate from code

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.