A systematic framework for technical documentation authoring.
The Grand Unified Theory of Documentation
—David Laing
The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product.
Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.
In Diátaxis, each of these modes (or types) answers to a different user need, fulfils a different purpose and requires a different approach to its creation.
Technical documentation should be structured explicitly around these four types, and should keep them all separate and distinct from each other.
In other words, what we call documentation is fundamentally not one thing, but four. Understanding the implications of this, and how those four different things work, can help improve most documentation.
While redesigning the Cloudflare developer docs, this content framework 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.
—Adam Schwartz (@AdamSchwartz)
Diátaxis promises to make documentation and projects better, and the teams that work with them more successful. It is light-weight, easy to understand and straightforward to apply. It doesn't impose implementation constraints.
Diátaxis is :ref:`proven in practice <adoption>` across a wide variety of fields and applications, in large and small, open and proprietary documentation projects.
.. toctree:: :maxdepth: 1 :hidden: :titlesonly: Home <self> Tutorials <tutorials> How-to guides <how-to-guides> Reference <reference> Explanation <explanation>
.. toctree:: :maxdepth: 1 :hidden: :titlesonly: needs Tutorials vs how-to guides <tutorials-how-to> how-to-use-diataxis
.. toctree:: :maxdepth: 1 :hidden: :titlesonly: adoption citation contact