Diátaxis: A Systematic Approach to Technical Documentation

What it is

Diátaxis is a framework for technical documentation created by Daniele Procida. Its central claim is that users come to documentation with four different needs, and each needs its own kind of page:

• Tutorials are learning-oriented: a guided lesson that takes a beginner through doing something meaningful.
• How-to guides are task-oriented: steps for someone who already knows what they want to achieve.
• Reference is information-oriented: accurate, complete descriptions of the machinery, such as an API reference or a configuration list.
• Explanation is understanding-oriented: discussion of why things are the way they are, background and trade-offs.

Most bad documentation mixes these, for example a tutorial that stops to list every option, or a reference page full of opinions. Diátaxis gives writers a vocabulary to spot and fix that.

Why it is worth your time

It is short, free and immediately usable. The site shows testimonials from organisations including Cloudflare, Gatsby and Vonage that used it to restructure their docs. For a student building a docs portfolio, explaining which Diátaxis type each page is, and why, is one of the clearest ways to show you think about readers.

It also helps developer advocates: a good tutorial and a good how-to guide are different pieces of writing, and knowing the difference improves your content.

Prerequisites

None. It helps to have a real documentation set in mind, such as a library you use or an open source project you want to contribute to, so you can sort its pages as you read.

How to use it

1. Read the four type pages and the section on the map that relates them.
2. Take an existing docs set and label each page with its type. Note pages that mix types.
3. Rewrite one mixed page into two clean ones.
4. When you plan new docs, decide the type first, then write.

Diátaxis suggests improving documentation in small iterations rather than a big redesign, which is also how docs work happens in real teams.

Free vs paid

The site is free to read. There is no paid tier.

Common questions

Is it a template? No. It tells you what kind of page to write, not how to lay it out. Pair it with templates, such as those from The Good Docs Project, and a style guide.

Do all docs need all four types? Not always. A small library may need a tutorial and a reference first. The framework helps you notice which needs are unmet.