Skip to content

Diátaxis Framework

Overview

Diátaxis1 was developed by Daniele Procida and offers a framework to guide writing technical documentation. It focuses on the user needs to determine where a piece of text should go.

Diátaxis uses two axes, to organise documentation into four main sections:

Practical versus theoretical
Is it about performing a certain task, or about understanding the backgrounds?
Study versus application
Is it about learning about a subject, or about using it for a specific purpose?

In a matrix view:

quadrantChart
    title Diátaxis Framework
    x-axis Study --> Application
    y-axis Theoretical --> Practical
    quadrant-1 How-to Guides
    quadrant-2 Tutorials
    quadrant-3 Explanation
    quadrant-4 Reference

How I use it

I use the framework to structure the navigation within each notes section.

The section index will contain a high-level introduction, and describe the scope of section. The pages will be divided into four main subsections.

Explanations
The "why?" and history behind concepts, tools, or choices I have made.
Tutorials
Study-oriented guides to start working with a process, technology or methodology.
How to
Practical guides to perform specific tasks.
Reference
Detailed information about a technology or methodology.

Note

I usually don't have content for all four kinds of notes.

Tip

The Diátaxis website has very helpful guidance and tips on how to write the different types of content, and good examples of its use.

  1. Daniele Procida. (n.d.). Diátaxis: A systematic framework for technical documentation authoring. Retrieved 12 February 2022, from https://diataxis.fr/
     ↩

  2. Daniele Procida. (2021, May 4). Always complete, never finished. Write the Docs, Portland. https://www.youtube.com/watch?v=Wc7n7uIg4AM
     ↩