Diátaxis

Contents

Menu

Expand

Light mode

Dark mode

Auto light/dark mode

Hide navigation sidebar

Hide table of contents sidebar

Home

Start here

Applying Diátaxis

Tutorials

How-to guides

Reference

Explanation

The compass

Workflow

Understanding Diátaxis

Foundations

The map

Quality

Tutorials and how-to guides

Reference and explanation

Complex hierarchies

Colophon

Back to top

Toggle Light / Dark / Auto color theme

Toggle table of contents sidebar

Diátaxis¶

A systematic approach to technical documentation authoring.

Diátaxis is a way of thinking about and doing documentation.

It prescribes approaches to content, architecture and form that emerge from a systematic approach to understanding the needs of documentation users.

Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.

Diátaxis, from the Ancient Greek δῐᾰ́τᾰξῐς: dia (“across”) and taxis (“arrangement”).

Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it).

As well as serving the users of documentation, Diátaxis has value for documentation creators and maintainers. It is light-weight, easy to grasp and straightforward to apply. It doesn’t impose implementation constraints. It brings an active principle of quality to documentation that helps maintainers think effectively about their own work.

Contents¶

The best way to get started with Diátaxis is by applying it after reading a brief primer.

Start here

These pages will help make immediate, concrete sense of the approach.

Applying Diátaxis

Tutorials

How-to guides

Reference

Explanation

The compass

Workflow

This section explores the theory and principles of Diátaxis more deeply, and sets forth the understanding of needs that underpin it.

Understanding Diátaxis

Foundations

The map

Quality

Tutorials and how-to guides

Reference and explanation

Complex hierarchies

Diátaxis is proven in practice. Its principles have been adopted successfully in hundreds of documentation projects.

Diátaxis has allowed us to build a high-quality set of internal documentation that our users love, and our contributors love adding to.

—Greg Frileux, Vonage

At Gatsby we recently reorganized our open-source documentation, and the Diátaxis framework was our go-to resource<br>throughout the project. The four quadrants helped us prioritize the user’s goal for each type of documentation. By<br>restructuring our documentation around the Diátaxis framework, we made it easier for users to discover the<br>resources that they need when they need them.

—Megan Sullivan

While redesigning the Cloudflare developer docs, Diátaxis 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

On this page

Diátaxis<br>Contents