Diátaxis Framework
(Content borrowed from Diataxis.fr and used here with the author's consent under a CC-BY-SA 4.0 license.)
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.
The Grand Unified Theory of Documentation
- David Laing
Four modes of documentation
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.
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.
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)
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 proven in practice across a wide variety of fields and applications. These include large and small, 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.