[DanieleProcida]

> 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.

[svat]

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.]