Diátaxis: a systematic approach to writing technical documentation

Diátaxis is a systematic approach to authoring technical documentation. Its author, Daniele Procida, presents it as a way of thinking about and doing documentation: it prescribes approaches to content, architecture and form that emerge from a study of what documentation users actually need.

Four kinds of documentation

The core idea is that there are fundamentally four identifiable kinds of documentation, responding to four different needs: tutorials, how-to guides, reference and explanation. Each has its own purpose and must be written in a different way. A tutorial is a lesson that takes a student by the hand through a learning experience — always practical, like a driving lesson. A how-to guide addresses a real-world goal or problem with practical directions for an already competent user; it is concerned with work rather than study. Reference documentation holds the technical facts a user needs in order to do things correctly — accurate, complete and free of interpretation, like a marine chart. Explanation provides context and background, joining things together and answering the question “why”.

A map and a compass

Diátaxis arranges the four kinds on a conceptual map, and adds a compass used to decide where a piece of content belongs. Tutorials and how-to guides are concerned with what the user does, that is, action; reference and explanation are about what the user knows, that is, cognition. Tutorials and explanation serve the acquisition of skill — the user’s study — while how-to guides and reference serve the application of skill — the user’s work. According to the project, crossing or blurring those boundaries lies at the heart of a vast number of problems in documentation.

Proven in practice

The approach is presented as light-weight, easy to grasp and free of implementation constraints, and its principles have been applied successfully in hundreds of documentation projects. Greg Frileux of Vonage says Diátaxis allowed a high-quality set of internal documentation to be built; Megan Sullivan reports that the Gatsby project relied on the framework while reorganizing its open-source documentation, using the four quadrants to prioritize each type of document; and Adam Schwartz recalls that while redesigning the Cloudflare developer docs, Diátaxis became “our north star for information architecture”.

How to start

The site’s own advice is to begin by applying it — to something, however small. The recommended working loop: look at the documentation in front of you, ask whether there is any way it can be improved, decide on one thing you could do right now, and do it; then repeat. No commitment to the theory is required — the author describes it as a wholly pragmatic approach whose value lies in helping people create better documentation.