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 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.
I Need To Write Documentation
I’ve been thinking a lot about documentation recently, experimenting with software such as Material for MkDocs and Docusaurus. These frameworks solve the problems of how and where to write documentation (Markdown files served as a static site by one of these frameworks together with static website hosting). However, they don’t solve the much more important problem of what to write about. There’s an entire field of technical writing.
I am now in a situation where I need to write several pieces of documentation. My client requested I create documentation for them based on what I’m working on, to both on-board new users/developers on how to work on the codebase and run pipelines, as well as two explain in-depth to any future DevOps Engineers or admins about how I set up our cloud infrastructure, repositories, custom tools and pipelines. Two pieces of documentation are needed. For the client, I will use Confluence; I am not a fan of Atlassian, but the alternative for this client is to write Word documents. Confluence will do. Besides, I’m not going to setup Docusaurus for this client.
At the same time, I also want to write documentation for my “homelab-as-code” project and to help write documentation for CALMe (together with Josh, who works as a technical writer).
Diátaxis
I learned about Diátaxis from Khue’s Homelab: Updating documentation (this website) - Khue’s Homelab
Khue’s Homelab is one of the most impressive homelab projects that I’ve seen. “Fully automated homelab from empty disk to running services with a single command”. It is also well documented. It uses the Diátaxis technical documentation framework:
There are 4 main parts:
- Getting started (tutorials): learning-oriented
- Concepts (explanation): understanding-oriented
- How-to guides: goal-oriented
- Reference: information-oriented
These four parts are the basis of Diátaxis:
At the core of Diátaxis are the four different kinds of documentation it identifies. If you’re encountering Diátaxis for the first time, start with these pages.
-
Tutorials - learning-oriented experiences
-
How-to guides - goal-oriented directions
-
Reference - information-oriented technical description
-
Explanation - understanding-oriented discussion
Diátaxis prescribes principles that guide action. These translate into particular ways of working, with implications for documentation process and execution. Once you’ve made your first start, the tools and methods outlined here will help smooth your way.
-
The compass - a simple tool for direction-finding
-
Workflow in Diátaxis
Should I Adopt Diátaxis?
On first impressions Diátaxis looks great. Writing it may be somewhat challenging at first as I learn to structure technical writing in this way, but the results may well be worth it. I am having a hard time finding alternative documentation frameworks (though I’m sure they exist). The alternative for me to using Diátaxis would be free-flow documentation based on the topics that I think I should cover; this is how I have been writing documentation until now which does work but may end up a bit messy. Of course, Diátaxis is not perfect either and there are criticisms for it: My Problem With the Four-Document Model.
]]>