• “Most useful when we're studying” and “Most useful when we're working” are clearer (and also more precise!) than abstract (“chunking”) terms like “Acquisition” and “Application”.
• Similarly, “Practical steps” and “Theoretical knowledge” are clearer than “Action” and “Cognition”.
• For that matter, the “-oriented” suffix in “Learning-oriented”, “Problem-oriented”, “Understanding-oriented”, “Information-oriented” is helpful, compared to the “Learning”, “Goals”, “Understanding”, “Information” abstract nouns.
What is common to all three sets of differences is that the former labels (on the older diagram) actually carry with them their semantic category (what kind of difference is being described, namely: (1) when useful, (2) what contents, (3) what's the orientation), while in the newer diagram everything is just abstract nouns. (E.g. “Useful during application” and “Useful during acquisition” would still be an improvement over just “Application” and “Acquisition”, though the older labels are even more direct and clear, without requiring the reader to engage in psychology to think abstractly about terms like acquisition.)
Also (separate complaint), whenever I want to tell anyone else about this "four kinds of documentation" approach, I always link to the archived https://web.archive.org/web/20200312220117/https://www.divio... which is the latest version that is entirely on a single page. Both the current version on the Divio site and on the Diataxis site seem “overdone”; a prospective reader has to click on “next” several times and it's unlikely they're going to do that.
> Also (separate complaint), whenever I want to tell anyone else about this "four kinds of documentation" approach, I always link to the archived https://web.archive.org/web/20200312220117/https://www.divio... which is the latest version that is entirely on a single page.
That's a mistake in my opinion. The big compass of four kinds of documentation I eye-catching and memorable, and I am sure it is part of the success of Diátaxis.
But what gets me out of trouble in my own work every time is https://diataxis.fr/compass/. It's one thing to have the general idea; it's another to be armed with an effective tool to apply to work.
The site doesn't just contain opinions and ideas, it also contains tools, that really are worth using.
It's the same "useful when we're learning" vs "useful when we're working" dichotomy, isn't it? :) When I want to tell someone about the idea of organizing their documentation into four buckets — or really, just about being conscious about the goals / the intended audience and usage — I really just want to plant a seed to have them open to the idea, i.e. at this point it's “Theoretical knowledge” rather than “Practical steps”. Later if they are persuaded they can go to diataxis.fr and learn more / get the “useful when we’re working” / “application” tools.
[Maybe diataxis.fr itself should be more clearly organized into an overview page (“explanation”), and separate sections for How-to guides and Reference. Right now it has an “Applying Diátaxis” and “Understanding Diátaxis” with a suggestion to start at the former, when in fact what I like most about documentation organized per the philosophy is that I as a reader can choose to start at the “Understanding” pages, instead of reading through tutorials and how-to guides and reference pages when I have not yet chosen to adopt whatever is being documented.]
Acquisition := Most useful when we're studying
Application := Most useful when we're working
Cognition := Theoretical knowledge
Action := Practical steps
...but in my mind, the older quadrant labels were immediately insightful at a glance.
Glad to learn that you've given your system a discoverable name though; for years since that PyCon presentation, I've informally recalled it as "the idea by that Django documentation guy".
• “Most useful when we're studying” and “Most useful when we're working” are clearer (and also more precise!) than abstract (“chunking”) terms like “Acquisition” and “Application”.
• Similarly, “Practical steps” and “Theoretical knowledge” are clearer than “Action” and “Cognition”.
• For that matter, the “-oriented” suffix in “Learning-oriented”, “Problem-oriented”, “Understanding-oriented”, “Information-oriented” is helpful, compared to the “Learning”, “Goals”, “Understanding”, “Information” abstract nouns.
What is common to all three sets of differences is that the former labels (on the older diagram) actually carry with them their semantic category (what kind of difference is being described, namely: (1) when useful, (2) what contents, (3) what's the orientation), while in the newer diagram everything is just abstract nouns. (E.g. “Useful during application” and “Useful during acquisition” would still be an improvement over just “Application” and “Acquisition”, though the older labels are even more direct and clear, without requiring the reader to engage in psychology to think abstractly about terms like acquisition.)
Also (separate complaint), whenever I want to tell anyone else about this "four kinds of documentation" approach, I always link to the archived https://web.archive.org/web/20200312220117/https://www.divio... which is the latest version that is entirely on a single page. Both the current version on the Divio site and on the Diataxis site seem “overdone”; a prospective reader has to click on “next” several times and it's unlikely they're going to do that.