.. meta::
   :description:
       The Diátaxis framework solves the problem of structure in technical documentation, making it easier to
       create, maintain and use.
   :keywords: documentation, four, kinds

.. _diataxis:

Diátaxis
========================================================

..  rubric:: A systematic framework for technical documentation authoring.

----------

..  epigraph::

    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.

..  sidebar::

    The name *Diátaxis* comes from the Ancient Greek δῐᾰ́τᾰξῐς: *dia* ("across") and *taxis*
    ("arrangement").

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.

.. image:: /images/diataxis.png
   :alt: Diátaxis
   :class: wider

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.

..  epigraph::

    While redesigning the `Cloudflare developer docs <https://developers.cloudflare.com>`_, 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 <https://github.com/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