Diátaxis: A Systematic Approach to Technical Documentation Authoring

Diátaxis (from the Ancient Greek for "across arrangement") is a way of thinking about how to write and structure documentation.

Placing the needs of documentation readers first, Diátaxis identifies four distinct user requirements, corresponding to distinct forms of documentation: tutorials, how-to guides, technical reference and explanation. Each form serves a unique purpose and requires a tailored writing approach. By keeping these content forms separate, Diátaxis ensures that documentation is structured effectively to meet its goals.

The framework also introduces a 2D grid with axes spanning from Acquisition to Application horizontally, and Action to Cognition vertically. The four documentation forms fit into the four quadrants of the grid: Learning (with tutorials), How-To Guides (with goals), Information (with technical references) and Understanding (with explanations). This visual model helps clarify the purpose of each documentation type. For example, how-to guides fall into the second quadrant, characterized by content focused on practical action and application. In addition to aiding end-users, this framework provides value to documentation creators and maintainers, as it helps them identify where within this structure new or updated information needs to be added.

In practice, documentation authoring is a challenging task. Having the Diátaxis structure in mind can help clarify into which of the content forms a particular idea might best fit; instead of force-fitting all documentation in a single manual. Certain concepts, though, can be difficult to categorize and might fit into multiple locations on the Diátaxis grid. So, like many tools and processes, this approach doesn't eliminate the complexity of technical work but provides a conceptual framework that somewhat simplifies it.