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
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.
In other words, what we call documentation is fundamentally not one thing, but four. Understanding the implications of this will help improve most documentation - often immensely.
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, and open and proprietary documentation projects.
If you’d prefer to watch a video covering this topic, here is it (courtesy of PyCon Australia 2017).