diataxis-documentation-framework

In the Diátaxis documentation framework, Explanation is a discursive treatment of a subject designed for understanding-oriented goals. Unlike how-to guides (task-oriented) or reference material (fact-oriented), explanation focuses on providing clarity, context, and reflection.

Key Characteristics

• Goal: To deepen and broaden the reader's understanding of a subject.
• Perspective: It takes a "higher and wider" view than other documentation types, focusing on an area of knowledge rather than a specific user task or a specific piece of machinery.
• Mental Model: It answers the question: "Can you tell me about ...?"
• Usage Context: It is documentation meant to be read for reflection, often away from the actual product (e.g., reading about architectural patterns rather than following a CLI command).

Alternative Names

If you are not calling a section "Explanation", you might use:

• Discussion
• Background
• Conceptual guides
• Topics

How-to guides are goal-oriented directions designed to guide a user through a specific problem or towards a practical result. They are concerned with work—navigating a user from a starting state to a completed task.

Characteristics

• Task-oriented: Focused on solving a specific problem or achieving a goal.
• Action-driven: Provides practical steps for the user to follow.
• Assumes competence: Written for users who already know what they want to achieve and possess basic domain knowledge.
• Goal-focused: Maintains strict focus on the task without unnecessary explanation, teaching, or reference material.

Examples

• Good (Specific Goal): how to calibrate the radar array; how to use fixtures in pytest; how to configure reconnection back-off policies.
• Bad (Open-ended/Vague): how to build a web application (this is a sphere of skill, not a specific task).

Benefits

A rich list of how-to guides serves as a functional map of what a product is actually capable of doing.

Diátaxis categorizes documentation into four distinct types based on the user's needs. Understanding these helps prevent the common problem of blurring boundaries between different documentation goals.

1. Tutorials: Lessons designed for learning. They are practical, guided experiences where an instructor (the writer) leads a student through a task to develop skills and confidence (e.g., 'Let's create a simple game in Python').
2. How-to guides: Practical directions for work. They address real-world goals or problems for already-competent users who need to get a specific task done (e.g., 'How to configure frame profiling').
3. Reference: Technical descriptions and facts for work. They provide accurate, complete, and neutral information (propositional knowledge) without interpretation or distraction (e.g., API documentation).
4. Explanation: Context and background for learning. They provide the 'why' and help the user understand the bigger picture, often involving opinions or different perspectives (e.g., 'Secure communication using HTTPS encryption').

Contents pages (Home and category landing pages) should not just be lists of links; they should act as overviews.

Best practices for landing pages:

• Provide Context: Use headings and introductory text to explain what the section covers.
• Avoid Long Lists: Humans struggle to read lists longer than seven items unless they have a mechanical order (numerical or alphabetical). If a list exceeds seven items, break it into smaller sub-groups.
• Introduce, Don't Just List: Use prose to introduce the content before presenting the links.

How to guides
============

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Installation guides
-------------------

Pellentesque malesuada, ipsum ac mollis pellentesque...

* Local installation       |
* Docker                   | links to guides
* Virtual machines         |
* Linux containers         |

Deployment and scaling
-----------------------

Morbi sed scelerisque ligula...

* Deploy an instance       |
* Scale your application   | links to guides

The Diátaxis compass is a decision-making tool used to determine the correct form of documentation based on two dimensions: whether the content informs action or cognition, and whether it serves the acquisition or application of skill.

To use the compass, ask two questions:

1. Action or Cognition?
   • Action: Practical steps, doing.
   • Cognition: Theoretical or propositional knowledge, thinking.
2. Acquisition or Application?
   • Acquisition: Study (learning a new skill).
   • Application: Work (using an existing skill).

By mapping the answers to this truth-table, you can identify the required documentation type:

You can apply this compass to evaluate existing documentation (to see if it needs to be moved or improved) or to plan new documentation.