A systematic approach to technical documentation authoring.
The Grand Unified Theory of Documentation
—David Laing
Diátaxis is an approach to :doc:`quality <quality>` in technical documentation. It describes an information architecture that emerges from a systematic approach to understanding the needs of documentation users.
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) corresponds to a different user need. Each 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 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, 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.
—Adam Schwartz (@AdamSchwartz)
Diátaxis is light-weight, easy to understand and straightforward to apply. It doesn't impose implementation constraints. It brings an active principle of quality to documentation. It helps make projects, and the teams that work with them, more successful.
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: Tutorials vs how-to guides <tutorials-how-to> Reference vs explanation <reference-explanation> needs compass quality Complex hierarchies <complex-hierarchies> how-to-use-diataxis
.. toctree:: :maxdepth: 1 :hidden: :titlesonly: adoption colofon