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.
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.