As a non writer I found that even without the details there's just one very important and very basic insight here:
You don't have to say everything exactly once.
Until being exposed to this idea I always tied myself in knots trying to write one stream of text that serves as THE DOCS. It's impossible to do this well (once you know, it seems very obvious haha). Just realising that you can write the same info in different ways for different readers is very helpful!
There is even a lot of potential for communicating more effectively here:
By giving 2-3 examples, that describe the same thing from slightly different aspects, you can to some extent overcome the ambiguities of language, by letting the reader figure out the common denominator between those examples, which will be a lot less ambiguous that only telling it from one example.
Let me give you two examples more [...] ;)
(Related, this is a technique used extensively by writers like king Solomon in the book of Proverbs in the Bible.)
Giving a few good examples also has the benefit of demonstrating the author's own understanding. If the author can't describe the matter in different ways, it shows don't have a feel for "it", and they're not grasping it rightly or even touching it at all. I've found that audiences can sense when a speaker is out-of-touch, and will politely ignore them.
Separately, I've heard that the Nicene Creed and its ancillaries had the repetitions hardcoded to forestall natural schism/emergent mutations in the generational belief system.
I have a friend who's a pastor. As a basic rule of a good sermon he always quoted the old addage: "Tell them what you’re going to tell them, tell them and tell them what you’ve told them".
There's more art to it, because there's also an off-putting way of doing that, which frequently shows up in presentations: you're greeted with a powerpoint slide with the topics in bullet points, which the presenter reads out loud, then come the slides with each of those points, also read out loud, and at the end there's a summary that almost copies the first slides, and which --for good measure-- is also read out loud. That makes me want to forget everything that's been told.
The anecdote doesn't strike me because your friend the pastor said it, but because it's a rule as old as times that every high-schooler was taught.
- The introduction should announce the thesis and its development
- walk your way towards your thesis
- The conclusion should summarize your thesis (and hint at openings towards new grounds)
But somehow, everyone seems to forget it and is in awe whenever someone recaps it.
Then the challenge becomes recording where each thing is recorded so that when it needs to be updated, you update it everywhere and don't end up with conflicting documentation.
True, even when you are writing a scientific publication with a hard page limits (~8 pages), it is advisable to reiterate the core messages multiple times as you add more context and details:
= abstract
1) in this paper we show that X holds by evaluating Y against Z
= intro
2) the problem of A is important because B, however the X aspect was overlooked; we show that evaluating Y highlights real world challenges, in contrast to Z, that...
3) to sum up, we found that Y is better at Z because X
= related work
Z approached the problem as..., which improved..., but as we show further, this is not sufficient to achieve...
.. and so on - you circle around the main message over and over again in each section.
We just applied this framework to the Sequin [1] docs two weeks ago. It has felt so nice to have a framework. I think our docs flow really well now, and it's been easier for us to add and maintain docs because we know where to put things.
The slightly ironic part is that the Diataxis docs themselves are a bit obtuse. It's a little verbose. So it took a couple passes for it all to click.
The analogy I gave my team that was helpful for everyone's understanding:
Imagine you're shopping for a piece of cooking equipment, like a pressure cooker.
The first thing you're going to look at is the "quickstart" (tutorial) – how does this thing work generally? You just want to see it go from A to B.
Then, you're going to wonder how to use it to cook a particular dish you like. That's a how-to.
If you're really curious about anything you've seen so far, then you'll flip to the reference to read more about it. For example, you might check the exact minutes needed for different types of beans.
And finally, when you're really invested in pressure cooking and want to understand the science behind it - why pressure affects cooking times, how the safety mechanisms work, etc. - that's when you'll read the explanatory content.
Comically, our docs were completely backwards: we lead with explanation ("How Sequin Works"). I think that's the natural impulse of an engineer: let me tell you how this thing works and why we built it this way so you can develop a mental model. Then you'll surely get it, right?
While that may be technically accurate, a person doesn't have the time or patience for that. You need to ramp them into your world. The quickstart -> how-to -> reference flow is a great way to do that. Then if you really have their attention, you can galvanize them about your approach with explanatory material.
I checked out your docs, and I agree that they flow very nicely! So often it seems that docs are either frustratingly vague to the point where it almost seems like the company is embarrassed to admit that their tool is a tool and not a "transformative synergy experience" (or similar nonsense), or docs immediately get overly specific without covering "why this product exists".
Minor note: The only thing in your docs that made me pause was the repeated use of "CDC", which I had to google the definition of. (For context, I have implemented "CDC" several times in my career, but wasn't familiar with the acronym)
I think having those four approaches is the key thing and you’re addressing it well. The flow is really the readers choice. My brain works in the way of wanting the overall explanation first. Then I seek the how-tos and tutorials.
On the other hand, systems like these might miss out on what users actually need. Diátaxis might work for a long time if technical documentation is only used in a documentation platform. However, if the same information could and should be used in more than one place—for example, in a UI, in a documentation portal, and in a mobile app—there might be need to break up information into smaller pieces in order to assemble them in different ways. This is known as 'content reuse', the practice of using the same content in multiple places. One approach on how to create and edit information for content reuse is described in the 'every page is page one' concept: https://everypageispageone.com/the-book/
If there's resources and time, I always recommend to do UX research at the very start of a project so that one doesn't later feel choked by a severely restricted information model. Nielsen/Norman have done a lot of research in this area and have interesting propositions on how to resolve issues around all of this, for example: https://www.nngroup.com/articles/information-foraging/#toc-w...
I don't see it. DITA differentiates between topic types such as task, reference, concept, etc., but a tutorial or a solution guide will be a combination of those topic types. Here I believe the focus is on deliverables that are larger than the individual topic.
Got an opinion on LwDITA ? Or are you deep enough into DITA that the complexity is not an issue ?
FWIW if you break up your content into reusable chunks and mark it up (with DITA or Docbook semantics, say), it should be a lot more amenable to being "understood" by a LLM... but I have not seen any data on this.
The trouble with DITA is that it is very often accompanied by its own very opinionated toolchain, although of course it's not mandatory. There are better ways to write docs nowadays than wrestle with XSL/FO and its brethren.
It's very popular in tech writing circles and pretty standard now as others have suggested.
We do see people try to take it too far though and have literally only these four categories on their docs page, which never works well imo.
It's mainly useful for a writer to keep in mind stuff like "it's a guide so focus on getting to result, not teaching" but in reality you don't want super hard lines. It's OK to have a bit of tutorial in a guide.
Only? For many projects having a medium quality version of just one of those would be an improvement.
----
Where the approach hits a wall in practice I think is when there is a lack of interconnection between the quadrants. E.g. for software frameworks, if the guides lack links to the references for specific classes/methods (which you ultimately will have to use), that makes exploring the surrounding context a lot harder. I have a few concrete frameworks in mind where there is a split along the quadrants and that's one of the biggest annoyances about their docs.
> We do see people try to take it too far though and have literally only these four categories on their docs page, which never works well imo.
Are you seeing experienced people cargo-culting or simply beginners to the framework being religious in its application?
I distinguish the two because I find that, when there's no other expert, a beginner is better off being dogmatic than trying to "do the right thing." By definition, a beginner does not have the expertise to make this decision. As you gain experience, you'll start to see where you need to deviate from the established rules.
Think of it like home-cooking to a recipe book vs being a professional chef throwing things in a pot to feel and taste.
I see it as a useful guide like any methodology should be. But I have worked with someone who insisted the rules should be followed to the letter, literally not a single sentence of explanation in any tutorial. So yes, that is the danger of these systems.
Eh, I've found that doc pages that try to establish really hard lines will still fail, and end up at a high level of quality. I think of it like a programming principle in the "don't mutate global variables" or "write shorter functions" category: you don't have to get it completely right, but most people really would be better off moving more in that direction rather than away from it.
The approach works better with dedicated technical writers. It makes sense to have distinct user-focused goals for documents before they’re written, and then just dig into the necessary parts of the software enough to make that happen as needed. When it’s developers doing the docs, they’re approaching it from the other end. They’ve got a chunk of code they need to cover, and reasoning about user needs is pretty difficult from that vantage point. Picking an approach vector when you don’t know the airport.
I think that's a SHOULD in the send of RFC 2119: "There may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course."
Treating a SHOULD as a MUST even when particular circumstances are against it, is one way to fail at a task.
It's like Orwell's last rule, where many people seem to miss that it's the punchline of the whole essay: "Break any of these rules sooner than say anything outright barbarous."
I recently saw someone praising the scikit-learn documentation, mentioning this page specifically https://scikit-learn.org/1.5/modules/grid_search.html so I took the top section and asked Claude to classify it with this framework:
> This piece appears to be primarily an Explanation with some elements of Reference mixed in. This documentation appears to be trying to serve multiple purposes, which according to Diátaxis is not ideal. The mix makes it less effective at both explaining and serving as reference. Following Diátaxis principles, this content might be better split into: 1) A pure explanation section about the concept and importance of hyperparameter tuning, and 2) A separate reference section listing the specific tools and methods available.
> This blending of documentation types is exactly what Diátaxis warns against when it says "Unfortunately, too many software developers think that auto-generated reference material is all the documentation required" and "The writer, intent on covering the topic, feels the urge to include instruction or technical description related to it. But documentation already has other places for these."
> HOWEVER. Let's look at why this integrated approach works well in a User Guide context:
> Natural Learning Flow: The documentation follows how people actually learn and use tools: 1) First understand what hyperparameters are, 2) Learn why you might want to tune them, 3) See what tools are available, 4) Get pointed to practical implementation examples
> Contextual Knowledge: By integrating explanation with technical details, users can immediately connect concepts to implementation. There's no need to jump between different documentation sections to piece together understanding.
> Progressive Disclosure: The documentation starts with fundamental concepts and progressively introduces more complex tools and considerations. This scaffolding helps users build understanding naturally.
> Practical Value: By combining explanation with specific tools and methods, users can immediately apply what they're learning. The documentation bridges theory and practice.
Having just completed my first (and last, for a while) shipping SwiftUI app, I very much think that documentation has been treated in shabby fashion, in the modern tech scene. I sorely miss the work done by all those great tech writers that Apple fired. Their engineers are terrible documenters.
I'm always a bit leery of "dogmatic" approaches, though, because they tend to develop a "priesthood," that refuses to bend; even when reality demands it.
In my experience, the initial developers of the dogma use it to marvelous effect, but subsequent "priests" screw the pooch; sometimes, turning the approach into a curse. Many good ideas have been destroyed by too-rigid applications (What is "Agile"?).
I see any documentation as having basically two faces: The maintainer, and the user. Each, has drastically different needs, and should probably be addressed by completely different teams.
As has been alluded to, in other comments, you can have issues with multiple instances of documentation, falling out of sync (the curse of most wiki-style documentation), but results matter. If the multiple instances can be effectively synced, then the documentation is effective and useful to its consumers. If no one reads the perfectly formatted and synced documentation, it's worthless.
On SNL, Phil Hartman[n] used to play The Anal-Retentive Chef. In one skit, he spent so much time prepping, that he couldn't actually demonstrate the recipe.
I see a lot of that, in tech. Toolchains and libraries that are absolutely perfect, but are unusable, in practice.
Documentation is an amalgam of many disciplines; human nature/psychology, graphic design, information architecture, technical infrastructure, publishing and distribution, etc.
I really think it's often treated as an afterthought, in most projects, and I believe that it should be a first-class consideration, at the Requirements stage, onwards.
I don't think of diataxis as a dogmatic approach, but rather a pragmatic one. You can dive pretty deep into the weeds in how to structure your documentation, but this is a very good training wheels until you find places that leak.
> Many good ideas have been destroyed by too-rigid applications
This is an interesting perspective that I disagree with. You seem to be saying that a general misunderstanding or misapplication of a good idea degrades the idea to a point that "destroys" it.
On the contrary, I believe there is experience to be gained in practice: either the initial idea wasn't good after all, in which case we're destroying an illusion; or the poor examples serve to refine the idea by clarifying some ambiguity that, interpreted wrongly, leads to failure.
Perhaps your argument is that many people may become familiar with the bad implementations and the idea's popularity will decline, depressing demand for refined implementations. This is likely true, but reflects the tragedy of the anticommons, not a degradation in the idea itself.
Well, what I mean, is that folks invest in the dogma, to the point where they refuse to accept any changes to fit realities, and often believe that they can apply the dogma, in areas, or in a manner, where it is not appropriate.
There's an old Swiss Army saying "When the map and the terrain disagree, believe the terrain.".
People who invest in dogma, refuse to look at the terrain. The map is The Only Source of Truth.
I believe that most dogma comes from something that works in one or more contexts, and may actually be highly effective, in other contexts, as long as it is adjusted for context. That last part, is what kills it. People refuse to change, and the dogma gets a bad name as a "failure."
Diátaxis is a great way to structure documentation, but I think its real value is in simplifying how we think about writing docs.
It shifts the focus from trying to cram everything into one ‘perfect document’ to recognizing that different users have different needs.
Like, tutorials are for learning by doing, guides are for solving specific problems, reference is for quick lookups, and explanations dive into the ‘why.’
That clarity alone can make one write useful docs.
That being said, sticking too rigidly to any system can be a trap.
We use it at our organisation and ever since we adopted it, our technical documentation is on a whole other level. That, page ownership and periodic reviews of each page by one of the page owners has made our technical documentation the only successful documentation effort that I've seen
I would say the author's Divio re-write at Diataxis.fr is less cluttered in its graphic but still essentially the same as the one that was used at Divio. I've always viewed the two references, for all intent and purpose, the same document for the ideas being presented in the context of their specific websites.
• “Most useful when we're studying” and “Most useful when we're working” are clearer (and also more precise!) than abstract (“chunking”) terms like “Acquisition” and “Application”.
• Similarly, “Practical steps” and “Theoretical knowledge” are clearer than “Action” and “Cognition”.
• For that matter, the “-oriented” suffix in “Learning-oriented”, “Problem-oriented”, “Understanding-oriented”, “Information-oriented” is helpful, compared to the “Learning”, “Goals”, “Understanding”, “Information” abstract nouns.
What is common to all three sets of differences is that the former labels (on the older diagram) actually carry with them their semantic category (what kind of difference is being described, namely: (1) when useful, (2) what contents, (3) what's the orientation), while in the newer diagram everything is just abstract nouns. (E.g. “Useful during application” and “Useful during acquisition” would still be an improvement over just “Application” and “Acquisition”, though the older labels are even more direct and clear, without requiring the reader to engage in psychology to think abstractly about terms like acquisition.)
Also (separate complaint), whenever I want to tell anyone else about this "four kinds of documentation" approach, I always link to the archived https://web.archive.org/web/20200312220117/https://www.divio... which is the latest version that is entirely on a single page. Both the current version on the Divio site and on the Diataxis site seem “overdone”; a prospective reader has to click on “next” several times and it's unlikely they're going to do that.
Acquisition := Most useful when we're studying
Application := Most useful when we're working
Cognition := Theoretical knowledge
Action := Practical steps
...but in my mind, the older quadrant labels were immediately insightful at a glance.
Glad to learn that you've given your system a discoverable name though; for years since that PyCon presentation, I've informally recalled it as "the idea by that Django documentation guy".
Readit News
You don't have to say everything exactly once.
Until being exposed to this idea I always tied myself in knots trying to write one stream of text that serves as THE DOCS. It's impossible to do this well (once you know, it seems very obvious haha). Just realising that you can write the same info in different ways for different readers is very helpful!
By giving 2-3 examples, that describe the same thing from slightly different aspects, you can to some extent overcome the ambiguities of language, by letting the reader figure out the common denominator between those examples, which will be a lot less ambiguous that only telling it from one example.
Let me give you two examples more [...] ;)
(Related, this is a technique used extensively by writers like king Solomon in the book of Proverbs in the Bible.)
Separately, I've heard that the Nicene Creed and its ancillaries had the repetitions hardcoded to forestall natural schism/emergent mutations in the generational belief system.
- The introduction should announce the thesis and its development - walk your way towards your thesis - The conclusion should summarize your thesis (and hint at openings towards new grounds)
But somehow, everyone seems to forget it and is in awe whenever someone recaps it.
= abstract 1) in this paper we show that X holds by evaluating Y against Z = intro 2) the problem of A is important because B, however the X aspect was overlooked; we show that evaluating Y highlights real world challenges, in contrast to Z, that... 3) to sum up, we found that Y is better at Z because X = related work Z approached the problem as..., which improved..., but as we show further, this is not sufficient to achieve...
.. and so on - you circle around the main message over and over again in each section.
...even the source code itself "says", in its own way, the same thing as the documentation, just to a different "audience" (the compilers)
Deleted Comment
The slightly ironic part is that the Diataxis docs themselves are a bit obtuse. It's a little verbose. So it took a couple passes for it all to click.
The analogy I gave my team that was helpful for everyone's understanding:
Imagine you're shopping for a piece of cooking equipment, like a pressure cooker.
The first thing you're going to look at is the "quickstart" (tutorial) – how does this thing work generally? You just want to see it go from A to B.
Then, you're going to wonder how to use it to cook a particular dish you like. That's a how-to.
If you're really curious about anything you've seen so far, then you'll flip to the reference to read more about it. For example, you might check the exact minutes needed for different types of beans.
And finally, when you're really invested in pressure cooking and want to understand the science behind it - why pressure affects cooking times, how the safety mechanisms work, etc. - that's when you'll read the explanatory content.
Comically, our docs were completely backwards: we lead with explanation ("How Sequin Works"). I think that's the natural impulse of an engineer: let me tell you how this thing works and why we built it this way so you can develop a mental model. Then you'll surely get it, right?
While that may be technically accurate, a person doesn't have the time or patience for that. You need to ramp them into your world. The quickstart -> how-to -> reference flow is a great way to do that. Then if you really have their attention, you can galvanize them about your approach with explanatory material.
[1] https://sequinstream.com/docs
PS: If you have any feedback on our docs, lmk :)
Minor note: The only thing in your docs that made me pause was the repeated use of "CDC", which I had to google the definition of. (For context, I have implemented "CDC" several times in my career, but wasn't familiar with the acronym)
https://github.com/sequinstream/sequin/commit/28bfba603da6d2...
What’s a CDC?
On the other hand, systems like these might miss out on what users actually need. Diátaxis might work for a long time if technical documentation is only used in a documentation platform. However, if the same information could and should be used in more than one place—for example, in a UI, in a documentation portal, and in a mobile app—there might be need to break up information into smaller pieces in order to assemble them in different ways. This is known as 'content reuse', the practice of using the same content in multiple places. One approach on how to create and edit information for content reuse is described in the 'every page is page one' concept: https://everypageispageone.com/the-book/
If there's resources and time, I always recommend to do UX research at the very start of a project so that one doesn't later feel choked by a severely restricted information model. Nielsen/Norman have done a lot of research in this area and have interesting propositions on how to resolve issues around all of this, for example: https://www.nngroup.com/articles/information-foraging/#toc-w...
I don't see it. DITA differentiates between topic types such as task, reference, concept, etc., but a tutorial or a solution guide will be a combination of those topic types. Here I believe the focus is on deliverables that are larger than the individual topic.
FWIW if you break up your content into reusable chunks and mark it up (with DITA or Docbook semantics, say), it should be a lot more amenable to being "understood" by a LLM... but I have not seen any data on this.
We do see people try to take it too far though and have literally only these four categories on their docs page, which never works well imo.
It's mainly useful for a writer to keep in mind stuff like "it's a guide so focus on getting to result, not teaching" but in reality you don't want super hard lines. It's OK to have a bit of tutorial in a guide.
Only? For many projects having a medium quality version of just one of those would be an improvement.
----
Where the approach hits a wall in practice I think is when there is a lack of interconnection between the quadrants. E.g. for software frameworks, if the guides lack links to the references for specific classes/methods (which you ultimately will have to use), that makes exploring the surrounding context a lot harder. I have a few concrete frameworks in mind where there is a split along the quadrants and that's one of the biggest annoyances about their docs.
Are you seeing experienced people cargo-culting or simply beginners to the framework being religious in its application?
I distinguish the two because I find that, when there's no other expert, a beginner is better off being dogmatic than trying to "do the right thing." By definition, a beginner does not have the expertise to make this decision. As you gain experience, you'll start to see where you need to deviate from the established rules.
Think of it like home-cooking to a recipe book vs being a professional chef throwing things in a pot to feel and taste.
I see it as a useful guide like any methodology should be. But I have worked with someone who insisted the rules should be followed to the letter, literally not a single sentence of explanation in any tutorial. So yes, that is the danger of these systems.
Treating a SHOULD as a MUST even when particular circumstances are against it, is one way to fail at a task.
It's like Orwell's last rule, where many people seem to miss that it's the punchline of the whole essay: "Break any of these rules sooner than say anything outright barbarous."
> This piece appears to be primarily an Explanation with some elements of Reference mixed in. This documentation appears to be trying to serve multiple purposes, which according to Diátaxis is not ideal. The mix makes it less effective at both explaining and serving as reference. Following Diátaxis principles, this content might be better split into: 1) A pure explanation section about the concept and importance of hyperparameter tuning, and 2) A separate reference section listing the specific tools and methods available.
> This blending of documentation types is exactly what Diátaxis warns against when it says "Unfortunately, too many software developers think that auto-generated reference material is all the documentation required" and "The writer, intent on covering the topic, feels the urge to include instruction or technical description related to it. But documentation already has other places for these."
> HOWEVER. Let's look at why this integrated approach works well in a User Guide context:
> Natural Learning Flow: The documentation follows how people actually learn and use tools: 1) First understand what hyperparameters are, 2) Learn why you might want to tune them, 3) See what tools are available, 4) Get pointed to practical implementation examples
> Contextual Knowledge: By integrating explanation with technical details, users can immediately connect concepts to implementation. There's no need to jump between different documentation sections to piece together understanding.
> Progressive Disclosure: The documentation starts with fundamental concepts and progressively introduces more complex tools and considerations. This scaffolding helps users build understanding naturally.
> Practical Value: By combining explanation with specific tools and methods, users can immediately apply what they're learning. The documentation bridges theory and practice.
I'm always a bit leery of "dogmatic" approaches, though, because they tend to develop a "priesthood," that refuses to bend; even when reality demands it.
In my experience, the initial developers of the dogma use it to marvelous effect, but subsequent "priests" screw the pooch; sometimes, turning the approach into a curse. Many good ideas have been destroyed by too-rigid applications (What is "Agile"?).
I see any documentation as having basically two faces: The maintainer, and the user. Each, has drastically different needs, and should probably be addressed by completely different teams.
As has been alluded to, in other comments, you can have issues with multiple instances of documentation, falling out of sync (the curse of most wiki-style documentation), but results matter. If the multiple instances can be effectively synced, then the documentation is effective and useful to its consumers. If no one reads the perfectly formatted and synced documentation, it's worthless.
On SNL, Phil Hartman[n] used to play The Anal-Retentive Chef. In one skit, he spent so much time prepping, that he couldn't actually demonstrate the recipe.
I see a lot of that, in tech. Toolchains and libraries that are absolutely perfect, but are unusable, in practice.
Documentation is an amalgam of many disciplines; human nature/psychology, graphic design, information architecture, technical infrastructure, publishing and distribution, etc.
I really think it's often treated as an afterthought, in most projects, and I believe that it should be a first-class consideration, at the Requirements stage, onwards.
I strongly suspect that few of the originators of dogma considered their work as such.
As I have gotten older, I have learned that "It Depends" is the only true dogma for almost all aspects of my life.
This is an interesting perspective that I disagree with. You seem to be saying that a general misunderstanding or misapplication of a good idea degrades the idea to a point that "destroys" it.
On the contrary, I believe there is experience to be gained in practice: either the initial idea wasn't good after all, in which case we're destroying an illusion; or the poor examples serve to refine the idea by clarifying some ambiguity that, interpreted wrongly, leads to failure.
Perhaps your argument is that many people may become familiar with the bad implementations and the idea's popularity will decline, depressing demand for refined implementations. This is likely true, but reflects the tragedy of the anticommons, not a degradation in the idea itself.
There's an old Swiss Army saying "When the map and the terrain disagree, believe the terrain.".
People who invest in dogma, refuse to look at the terrain. The map is The Only Source of Truth.
I believe that most dogma comes from something that works in one or more contexts, and may actually be highly effective, in other contexts, as long as it is adjusted for context. That last part, is what kills it. People refuse to change, and the dogma gets a bad name as a "failure."
You see this constantly.
It shifts the focus from trying to cram everything into one ‘perfect document’ to recognizing that different users have different needs.
Like, tutorials are for learning by doing, guides are for solving specific problems, reference is for quick lookups, and explanations dive into the ‘why.’
That clarity alone can make one write useful docs.
That being said, sticking too rigidly to any system can be a trap.
1: https://docs.divio.com/documentation-system/
I would say the author's Divio re-write at Diataxis.fr is less cluttered in its graphic but still essentially the same as the one that was used at Divio. I've always viewed the two references, for all intent and purpose, the same document for the ideas being presented in the context of their specific websites.
• “Most useful when we're studying” and “Most useful when we're working” are clearer (and also more precise!) than abstract (“chunking”) terms like “Acquisition” and “Application”.
• Similarly, “Practical steps” and “Theoretical knowledge” are clearer than “Action” and “Cognition”.
• For that matter, the “-oriented” suffix in “Learning-oriented”, “Problem-oriented”, “Understanding-oriented”, “Information-oriented” is helpful, compared to the “Learning”, “Goals”, “Understanding”, “Information” abstract nouns.
What is common to all three sets of differences is that the former labels (on the older diagram) actually carry with them their semantic category (what kind of difference is being described, namely: (1) when useful, (2) what contents, (3) what's the orientation), while in the newer diagram everything is just abstract nouns. (E.g. “Useful during application” and “Useful during acquisition” would still be an improvement over just “Application” and “Acquisition”, though the older labels are even more direct and clear, without requiring the reader to engage in psychology to think abstractly about terms like acquisition.)
Also (separate complaint), whenever I want to tell anyone else about this "four kinds of documentation" approach, I always link to the archived https://web.archive.org/web/20200312220117/https://www.divio... which is the latest version that is entirely on a single page. Both the current version on the Divio site and on the Diataxis site seem “overdone”; a prospective reader has to click on “next” several times and it's unlikely they're going to do that.
Glad to learn that you've given your system a discoverable name though; for years since that PyCon presentation, I've informally recalled it as "the idea by that Django documentation guy".