Skip to content

A Framework for Better Documentation

Diataxis Framework

I recently came across an awesome framework for creating better technical documentation: The Diátaxis framework developed by Daniele Procida. It is a well-structured system that you can immediately apply to improve your software documentation. The basic idea goes like this.

Four Types of Documentation

The framework distinguishes between four fundamental types of documentation.

  1. Tutorials
  2. Guides
  3. Reference
  4. Explanation

Each type of documentation is geared towards a specific audience and purpose.

Tutorials

The main goal of a tutorial is to help beginners getting started. The focus is on learning and acquiring the competencies required to use the software. The tutorial should contain step-by-step instructions. Each step should be easily attainable and provide concrete, meaningful results. The structure should be clear and linear. After completing the tutorial, the user should be ready to work with the other parts of the documentation to proceed his learning.

Audience: Beginners
Purpose: Learning

Guides

How-to guides contain precise directions how to achieve a specific goal using the software. In contrast to learning-oriented tutorials, a guide is a form of task-oriented documentation. The user has a concrete question in mind, such as “How do I write a mesh to a file?”. A guide already assumes a certain degree of familiarity with the subject area. Unnecessary details can be omitted. The goal is not to give the full picture. The focus is on helping the user while he is working with the software.

Audience: Intermediate
Purpose: Problem-solving

Reference

This is the technical reference documentation that describes in detail how the machinery works. In case of a software library, this is most likely the API reference. The main goal of this type of documentation is information. To support this, it should be very concise and to the point. However, this should also include common pitfalls to be aware of.

Audience: Experienced
Purpose: Information retrieval

Explanation

This is the more detailed background material that further clarifies the understanding of the software. An in-depth overview of the design of a library might be a good example. Something you’re interested in when you want to understand the internals of the system. Might also go by the names background, discussion, or conceptual guides.

Audience: Experts, developers
Purpose: Understanding

Wrapping Up

Obviously, I’m only scratching the surface here. If you want to dive deeper, have a look at the full description at diataxis.fr. There is also a conference presentation by Daniele Procida on the same subject.

Overall, the framework looks very well thought out to me. At least, it made me think about adapting documentation towards specific audiences and keeping their needs in mind. I hope I’ll find some time to put this into practice for PMP.

Hope this helps!

Further Reading