What is the Diataxis framework?

Diataxis is a documentation model developed by Daniele Procida that organises content into four modes: tutorials, how-to guides, reference, and explanation. Each mode serves a different user need.

What are the four types of documentation in Diataxis?

Tutorials teach step by step, how-to guides solve a specific problem, reference gives precise factual detail, and explanation builds understanding of the underlying concepts.

When should you use the Diataxis framework?

It works best for complex or mature products with substantial documentation. For very simple products it can be more structure than you need.

Diataxis framework: the best documentation model?

This is human generated content.

Tutorials
How-to guides
Reference
Explanation
Why Diataxis?
When to use Diataxis
Conclusion
Work with Weesho Lapara
Additional resources

Diátaxis is a framework based on empirical research by Daniele Procida, who identified four information patterns for creating high-quality technical documentation that meets the needs of different types of users. It is based on the idea that documentation should be structured around four modes: tutorials, how-to guides, reference, and explanation. Each mode has a different purpose, audience, and style, and should be treated as a distinct type of content.

Tutorials

Tutorials are lessons that teach users how to do something step-by-step, using hands-on exercises and examples. They are designed for beginners who want to learn new skills or concepts. Tutorials should be clear, concise, and engaging, and should provide feedback and guidance along the way.

How-to guides

How-to guides are practical guides that show users how to solve specific problems or achieve certain goals. They are designed for intermediate or advanced users who have some prior knowledge or experience. How-to guides should be detailed, comprehensive, and accurate, and should provide clear instructions and tips.

Reference

Reference is information that helps users find answers to their questions or use features of the product. It is designed for experienced users who know what they are looking for. Reference should be organised, searchable, and consistent, and should provide definitions, descriptions, examples, and links.

Explanation

Explanation is information that helps users understand the underlying principles or concepts of the product. It is designed for curious users who want to learn more about how things work or why they work that way. Explanation should be informative, logical, and relevant, and should provide context, background, rationale, and implications.

Why Diataxis?

Diátaxis is not just a framework; it is a philosophy of documentation design that aims to improve user satisfaction and product success. Users can find the information they need in the most appropriate mode for their situation.

Diátaxis framework also makes the process of creating, maintaining, and updating documentation easier since the contents are separated by type. Moreover, your documentation remains consistent in quality. Bascially:

It provides a solid foundation for creating quality documentation.
It offers a clear structure for organizing content by type.
It supports collaboration among different stakeholders involved in documentation.
It fosters continuous improvement through evaluation and revision.

When to use Diataxis

Diátaxis is not perfect; it has its limitations and challenges. For example:

It requires careful planning and analysis before starting any documentation project.
It may not suit every product or domain; some products may have more complex or diverse user needs than others.
It may not account for all possible scenarios or variations; some situations may require more flexibility or customisation than others.
It may not address all possible issues or feedback; some problems may arise from unexpected sources or contexts.

Conclusion

Diataxis is less a template than a philosophy: structure documentation around the four things readers actually come for. Adopt it where your product is complex enough to benefit, and you get documentation that is easier to navigate, easier to maintain, and more satisfying to use.

But Diátaxis is also not the only documentation model out there; there are other frameworks and approaches that may work better for certain products or teams.

For example, some products may benefit from a more user-centered design approach that focuses on user personas, user journeys, and user feedback.

Fabrizio Ferri-Benedetti’s Seven Action Documentation model is also another alternative that categorises documentation into seven types based on user actions: learn, use, troubleshoot, extend, integrate, contribute, and advocate.

Work with Weesho Lapara

Thinking about restructuring your documentation around Diataxis? Book a consult or get in touch and we will help you plan the information architecture.

Table of contents