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.