Thank you for posting that, I totally agree with @hillelogram.
My documentation holy grail for large codebases is a codebase that starts with literate programming style programmer documentation, then pinned against tags to that structure is a programmer reference documentation, then pinned against that programmer reference are architecture, devops, and user reference, and cascading onwards to a fully-interlinked structure where the user manual is towards the "leafy edges", and demos/tutorials are all the way at the ending leaves. Smaller codebases can skip with "deep-linking tags" that just jump to say a man page or similar.
I basically want a Nix for documentation dependency management. Where if I change how some code behaves, I can see the vast majority of the documentation that change impacts.
The doc smell of a chaotically-organized documentation source: when the program version changes, every page in the old version when you try to switch to the new version says it cannot find an equivalent page and offers to jump you to the beginning of the new version documentation. I've heard this called "version aphasia". It is especially frustrating to discover that in the new version there is an exact section with the exact section title, organized in the exact same heading structure.
Documentation dependency management is still in the Precambrian era compared to source code, and we aren't doing so hot IMHO there, either.
I think Procida initially created this as part of their work with Divio and then forked it to the Diataxis site. The Divio site was definitely around before Diataxis and the Divio site was where these ideas originally gained a lot of popularity.
They’re officially related. Personally, prefer the link I used since it provides a table of contents and link to this YouTube presentation on the system:
It's already a weakness of this "theory" that it leaves only the reference for documentation that's intended to be complete and correct, while also recommending that the reference be organised as a list of the available operations.
But this divio variant goes so far as to say that, when writing the reference, "don't allow explanations of concepts".
I believe good documentation often needs rigorous definitions of the concepts involved, not just a list of functions or configuration items or whatever.
So either the reference should have space for those, or the explanation should be in a more rigorous style, not a "more relaxed" discussion.
There's also a separate dimension for consuming vs developing. Probably this sits under the category of "too obvious to point out". But still, in large orgs I frequently see wikis that have stuff meant for team members and stuff meant for consumers of the service, with no clear separation.
Interesting point. Generally, in my experience, specifications, that is the documents produced prior to building a system are replaced by the documentation that’s created after the system is built.
I have seen some projects try to keep the specs updated, even fewer that try to keep the specs/build/docs in sync via tagging and unique IDs.
If the specs were within this framework, my guess is they would go under reference; for example, an API spec would easily be kept in sync and would naturally go under the reference section. In fact, the example given is for a CLI:
I agree these don't fit into the 4Ds because the spec is many times the contractual document used for handover compliance line item by line item as part of a larger RFP. Much of it should end up in permanent operational documents but you keep the baseline fixed (with amendments) to compare the original intent against what you end up with. Still, I'm not sure this matters enough to add another D to the taxonomy. If I was to add one it would be D for Diagrams which matter enough to be a category of their own ;}
The analogies from cooking are not great. If anything, the weird distinctions they draw (recipes are not tutorials? and how-tos have to focus on an end, not a technique?) really underline how the theory proposed has been oversimplified. Just like the gap between "teaching a child to cook" and "a recipe for brioche" is actually pretty huge, I constantly hear from users that there is not enough "advanced beginner" material in the documentation for projects I have worked on.
Perfect timing! Last week I struggled to write documentation that would leave me satisfied - this framework explains why: I tried to write a reference, how-to and explanation at the same time. And it also offers the solution: Split it into three parts (create them if they don't exist yet).
