Skip to content

About Documentation Architecture

This article explains why we organize documentation using the Diátaxis framework and how it helps both readers and writers.

What is Diátaxis?

Diátaxis is a systematic approach to technical documentation that identifies four distinct types of content, each serving different user needs:

  1. Tutorials - Learning-oriented
  2. How-to Guides - Goal-oriented
  3. Reference - Information-oriented
  4. Explanation - Understanding-oriented

Why Use Diátaxis?

For Readers

Documentation organized with Diátaxis helps users find what they need quickly:

  • When learning: They know to start with Tutorials
  • When working: They can jump to How-to Guides for specific tasks
  • When double-checking: They consult Reference for accurate details
  • When deepening knowledge: They read Explanation for context

This clear separation means users spend less time searching and more time accomplishing their goals.

For Writers

Diátaxis provides clarity for documentation authors:

  • Clear scope: Each page type has well-defined boundaries
  • Consistent structure: Similar pages follow similar patterns
  • Easier maintenance: Changes stay focused and contained
  • Quality assurance: Easy to evaluate if content serves its purpose

The Four Quadrants

Tutorials: Learning by Doing

Tutorials are lessons that take users through a meaningful exercise. Think of teaching a child to cook - the goal isn't perfection, it's building confidence and familiarity.

Characteristics:

  • Practical, hands-on exercises
  • Safe, reliable outcomes
  • Learning happens through doing
  • No assumptions about prior knowledge

How-to Guides: Solving Problems

How-to guides are recipes for accomplishing specific goals. They assume competence and focus purely on getting things done.

Characteristics:

  • Addresses real-world problems
  • Goal-oriented steps
  • Assumes basic competence
  • Omits unnecessary explanation

Reference: Technical Truth

Reference material is the map of your system. It describes what things are and how they work, with precision and completeness.

Characteristics:

  • Authoritative and accurate
  • Structured by the system itself
  • Dry, factual descriptions
  • No opinions or judgements

Explanation: Understanding Context

Explanation provides the bigger picture. It discusses the "why" behind decisions, connects concepts, and deepens understanding.

Characteristics:

  • Provides context and background
  • Makes connections
  • Discusses alternatives
  • Can include opinions and perspectives

Why This Matters

Traditional documentation often mixes these types together, creating confusion:

  • Tutorials that try to explain everything (overwhelming learners)
  • Reference that includes too many examples (hard to find facts)
  • How-to guides that teach instead of guide (frustrating experienced users)

By separating these concerns, Diátaxis creates documentation that serves everyone better.

The Documentation Journey

Users typically move through documentation in a natural progression:

  1. Start with Tutorials - Build initial confidence and basic skills
  2. Use How-to Guides - Accomplish real work with the product
  3. Consult Reference - Verify details and check options
  4. Read Explanation - Deepen understanding and master the craft

This isn't a strict sequence - users jump between types as needed - but it represents a natural learning arc from beginner to expert.

Further Reading