Unified theory of documentation systems

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.

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:

https://m.youtube.com/watch?v=t4vKPhjcMZg

This variant seems worse than the dataxis one.

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.

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.

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:

https://docs.divio.com/en/latest/reference/divio-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 ;}