Comment by hambes
2 years ago
I think the graphic used by divio[1] ist so much more intuitive. But seems Diátaxis has more comprehensive documentation on what they mean.
2 years ago
I think the graphic used by divio[1] ist so much more intuitive. But seems Diátaxis has more comprehensive documentation on what they mean.
https://diataxis.fr/colophon/#origins-and-development
I would say the author's Divio re-write at Diataxis.fr is less cluttered in its graphic but still essentially the same as the one that was used at Divio. I've always viewed the two references, for all intent and purpose, the same document for the ideas being presented in the context of their specific websites.
Why do you think the version on the Divio site is better - what's more intuitive about it?
Not the GP, but I agree:
• “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.
1 reply →
I can see your attempts to generalize, i.e.
...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".
Not GP but thought of the exact thing when seeing this - look at the wording on the axes.