Diátaxis is successful because it works - both users and creators have a better experience of documentation as a result. It makes sense and it feels right.
However, that's not enough to be confident in Diátaxis as a theory of documentation. As a theory, it needs to show why it works. It needs to show that there is actually some reason why there are exactly four kinds of documentation, not three or five. It needs to demonstrate rigorous thinking and analysis, and that it stands on a sound theoretical foundation.
Otherwise, it will be just another useful heuristic approach, and the strongest claim we can make for it is that "it seems to work quite well".
Diátaxis is based on the principle that documentation must serve the needs of its users. Knowing how to do that means understanding what the needs of users are.
The user whose needs Diátaxis serves is the practitioner in a domain of skill. A domain of skill is defined by a craft - the use of a tool or product is a craft. So is an entire discipline or profession. Using a programming language is a craft, as is flying a particular aircraft, or even being a pilot in general.
Understanding the needs of these users means in turn understanding the essential characteristics of craft or skill.
A skill or craft or practice contains both action (practical knowledge, knowing how, what we do) and cognition (theoretical knowledge, knowing that, what we think). The two are completely bound up with each other, but they are counterparts, wholly distinct from each from each, two different aspects of the same thing.
Similarly, the relationship of a practitioner with their practice is that it is something that needs to be both acquired, and applied. Being "at work" (concerned with applying the skill and knowledge of their craft) and being "at study" (concerned with acquiring them) are once again counterparts, distinct but bound up with each other.
This gives us two dimensions of skill, that we can lay out on a map - a map of the territory of craft:
This is a complete map. There are only two dimensions, and they don't just cover the entire territory, they define it. This is why there are necessarily four quarters to it, and there could not be three, or five. It is not an arbitrary number.
It also shows us the qualities of craft that define each of them. When the idea that documentation must serve the needs of craft is applied to this map, it reveals in turn what documentation must be and do to fulfil those obligations - in four distinct ways.
The map of the territory of craft is what gives us the familiar Diátaxis map of documentation. The map is in effect an answer to the question: what must documentation do to align with these qualities of skill, and to what need is it oriented in each case?
We can see how the map of documentation addresses needs across those two dimensions, each need also defined by the characteristics of its quarter of the map.
| need | addressed in | the user | the documentation |
|---|---|---|---|
| learning | tutorials | acquires their craft | informs action |
| goals | how-to guides | applies their craft | informs action |
| information | reference | applies their craft | informs cognition |
| understanding | explanation | acquires their craft | informs cognition |
The Diátaxis map of documentation is a memorable and approachable idea. But, a map is only reliable if it adequately describes a reality. Diátaxis is underpinned by a systematic description and analysis of generalised user needs.
This is why the tutorials, how-to guides, reference and explanation of Diátaxis are a complete enumeration of the types of documentation that serve practitioners in a craft. This is why there are four and only four types of documentation. There is simply no other territory to cover.