> In short, the 4doc model is not universal. It was designed for documenting tools and doesn’t fully address the needs of frameworks and programming languages.
I think that the author is onto something here, but I'm not sold on the exact example that the author provides (programming languages). Honest question: are the Python docs deeply loved by the Python community? In other words, should we be holding up the Python docs as an example of great docs and therefore an example that the 4doc model is inadequate? I've done a fair bit of Python programming myself. In my experience the Python docs are decent: not great, not terrible. If we look at the Rust docs, which seem to get much more praise than the Python docs, then the author's argument seems to break down for me a bit. Because the Rust docs seem to be more aligned with the 4doc model than the Python docs, and the Rust docs are more praised than the Python docs.
One domain where I recently saw the limitations of the 4doc model is OS bringup. I was writing docs explaining how to get an OS running on new hardware. Customer feedback suggested that the ideal doc would start off as an overview, and then morph into a guide, but the guide section would also need constant small explanations of conceptual stuff.
I also agree with the "it's not comprehensive" premise but again the example fell flat for me. Conceptual overviews totally overlap with explanations. I can elaborate if needed but I honestly think the author is imposing a narrow definition of explanations that does not exist in the 4doc model.
The main instances where the 4doc model is glaringly incomplete for me are homepages and release notes. You can kinda bucket homepages under explanations or references. And you can kinda bucket release notes under references. But those classifications are a stretch. The fact that practically every technical project needs a homepage and most need release notes really suggests to me that they are their own categories and deserve unique guidelines.
The key here would be to go back to goal-focused thinking. My guess for the #1 reason for 4doc's success is how it aligns each doc type with a goal:
* Tutorials - Learning
* How-To Guides - Tasks
* Explanations - Understanding
* References - Information
If you're going to propose a new universal doc type, you should be able to propose a new universal goal type as well. My argument about release notes begins to fall short here: release notes are totally about information so they should probably just get bucketed cleanly under references. But I think my argument about homepages holds its ground better:
* Homepages - Convincing
MAYBE (but probably not) we can save release notes like this:
* Release Notes - Diffing
The Pigweed docs might be an interesting example of where the 4doc model falls short. Here in SEED-0102 (our docs plan) you can see how the 4doc model is the foundation but we felt the need to define further categories of docs. In terms of domains (recall how the author suggested the 4doc is good for tools but not programming languages) Pigweed is a collection of a bunch of stuff for embedded development (libraries, tools, etc.) so that could explain why we needed to define more doc types. https://pigweed.dev/seed/0102-module-docs.html
The topic of examples came up recently on the Write The Docs Slack. Daniele Procida had a very thoughtful response. Original comment from Rob H:
> I tend to like to categorize some of my items by whether or not they have "examples," which seems to be an attribute that could apply to multiple diataxis types, but not a standalone type by itself. I could use a tag on these items with the word "examples," but I feel almost like it needs a category by itself, given that it seems to be my learning style. But then there's another twist: in some cases, an "example" is more of an "inspiration for a way to use something," and in others, an "example" is more of a "clarifier that completes the learning process."
Response from Procida:
> You can and probably should use examples everywhere. I think that a well-crafted example can often illuminate something much better than a painstaking attempt to describe it fully and completely. In every aspect of life in fact. I bet that you can think of someone who was an example to you, of say moral righteousness, that taught and inspired you more than any amount of moral theorising and argument (I certainly can). Examples are very powerful, and we are intelligent, so we use them very well when we encounter them. Examples illustrate extremely effectively, whether they are illustrating how-to guides, explanation, or whatever. But examples on their own seem a bit deracinated. What are they examples of? Don’t they need context?