.. 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 Diátaxis Framework ======================================================== .. rubric:: A systematic framework for technical documentation authoring. 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. ============= .. rst-class:: quote The Grand Unified Theory of Documentation .. rst-class:: attribution \- David Laing ============= Four modes of documentation ---------------------------- .. sidebar:: *Diátaxis* From the Ancient Greek δῐᾰ́τᾰξῐς - *dia*, "across", and *taxis*, "arrangement". The framework identifies four modes of documentation - **tutorials**, **how-to guides**, **technical reference** and **explanation**. 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. .. image:: /images/diataxis.png :alt: 'Diátaxis' 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. Diátaxis promises to make documentation and projects better, and the teams that work with them more successful. ==================== .. rst-class:: quote 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. .. rst-class:: attribution \- Adam Schwartz (`@AdamSchwartz `_) ==================== Light-weight and easily adopted ----------------------------------- The framework is light-weight, easy to understand and straightforward to apply. It doesn't impose implementation constraints. Complete and comprehensive ---------------------------- Diátaxis provides a comprehensive and nearly universally-applicable scheme, that has been :ref:`proven in practice across a wide variety of fields and applications `. These include large and small, and open and proprietary documentation projects. Video presentation ------------------ Here is a video of a conference talk presenting the concepts encapsulated in Diátaxis, from PyCon Australia 2017. .. raw:: html

.. toctree:: :maxdepth: 0 :hidden: :titlesonly: Home introduction tutorials how-to-guides reference explanation adoption how-to-use-diataxis Development