Diátaxis

Diátaxis is a systematic methodology designed for the authoring of technical documentation. Rather than relying on intuition, it provides a structured approach to content, architecture, and form, all of which are derived from a rigorous analysis of the actual needs of the people reading the documentation.

At its core, Diátaxis recognizes that users have four distinct needs, which require four specific formats of documentation:

1. Tutorials
2. How-to guides
3. Technical reference
4. Explanation

By establishing a systematic relationship between these forms, Diátaxis suggests that the documentation's overall organization should mirror the structure of these user needs.

Etymology and Purpose

The term Diátaxis originates from the Ancient Greek $\delta\iota\alpha\tau\alpha\xi\iota\varsigma$, where: $\text{dia (across)} + \text{taxis (arrangement)} = \text{Diátaxis}$

This framework is designed to eliminate randomly organized content and instead solve specific problems regarding:

• Content: Determining what needs to be written.
• Style: Deciding how it should be written.
• Architecture: Defining how to organize the information.

While primarily benefiting the end-user, Diátaxis is equally valuable for the creators and maintainers of documentation. It is light-weight, simple to understand, and easy to implement. It introduces an active principle of quality, allowing maintainers to evaluate their work with a critical and effective lens.

---

🗺️ Framework Overview

The relationship between the four types of documentation can be visualized as a matrix of Learning vs. Doing and Practical vs. Theoretical.

Comparison of Documentation Forms

---

📖 Navigation Guide

The most effective way to adopt Diátaxis is to read a brief primer and then begin applying it.

🚀 Start Here

These resources provide immediate, concrete utility for implementing the approach:

• Applying Diátaxis
• Tutorials
• How-to guides
• Reference
• Explanation
• The compass
• Workflow

🧠 Understanding Diátaxis

For those seeking a deeper dive into the underlying theory and the nature of user needs, explore these sections:

• Foundations: The core philosophy.
• The map: Visualizing the architecture.
• Quality: Defining what "good" looks like.
• Tutorials and how-to guides: Deep dive into practical content.
• Reference and explanation: Deep dive into theoretical content.
• Complex hierarchies: Managing large-scale documentation.

---

🛠️ Implementation Example

If you were to represent the Diátaxis structure in a configuration file for a documentation site, it might look like this:

{
  "documentation_structure": {
    "learning_oriented": ["tutorials", "explanation"],
    "performance_oriented": ["how_to_guides", "reference"],
    "principles": "systematic_arrangement"
  }
}

---

🌟 Proven Success

Diátaxis is not merely theoretical; it has been successfully integrated into hundreds of real-world projects.

"Diátaxis has allowed us to build a high-quality set of internal documentation that our users love, and our contributors love adding to." — Greg Frileux, Vonage

"At Gatsby we recently reorganized our open-source documentation, and the Diátaxis framework was our go-to resource throughout the project. The four quadrants helped us prioritize the user’s goal for each type of documentation... we made it easier for users to discover the resources that they need when they need them." — Megan Sullivan, Gatsby

"While redesigning the Cloudflare developer docs, Diátaxis became our north star for information architecture. When we weren’t sure where a new piece of content should fit in, we’d consult the framework. Our documentation is now clearer than it’s ever been, both for readers and contributors." — Cloudflare