I and my team did a full set of documentation for handing over a codebase to the client. A large complex codebase with accumulated history and subtle reasons why things were done.
Diataxis was fantastic. It took a bit of effort to work out what the page titles were to cover everything we needed, but then when you were writing a page it was glorious.
It was so clear what you were saying and what "voice" you were writing in. If it's a Reference page you're all descriptive, with diagrams and bullet points. When it's a guide you're more discursive, but you know you're just imparting information not trying to teach. It made it so much easier to be coherent and clear about everything.
We just invested a good amount of time restructuring our docs for Diátaxis. It was helpful, but I wouldn't take it as gospel. The important thing to remember is that each piece of content should be one of the four types.
If you're embarking upon a refactoring / rewriting journey for your docs, the only advice I'd share is to actually read the website beginning to end before starting. Especially this page: https://diataxis.fr/complex-hierarchies/. The guide is (unsurprisingly) very well written, and it's easy to internalize the concepts because they're repeated often.
I never saw the point in Diataxis, but honestly while vibe coding it's pretty convenient to tell an LLM "do diataxis" and get decent first pass documentation out of it.
Ive been aware of diataxis for a while, but i hadnt considered such an approach. Will definitely keep it in mind for when im ready to generate some sort of docs. Thanks!
I love seeing this pop up again. Our customer support team has been steadily moving all of our docs over to Diátaxis for a while and it's been a really nice improvement.
Another documentation model: Fabrizio's seven actions [0]. People read docs to appraise, understand, explore, practice, remember, develop, and troubleshoot, usually in that order.
It feels so natural and obvious compared to Diataxis' forced abstractions, where I'm still left wondering "what's the difference between a tutorial and a how-to guide?"
But! I'm glad for anything that helps people organize and maintain docs.
> ...where I'm still left wondering "what's the difference between a tutorial and a how-to guide?"
I don't find this question difficult. Without looking anything up, a tutorial exercises a contrived example for learning purposes, whereas a how-to guide provides instructions suitable for real world execution.
How to guide is for things which you want to do, probably not without going in depth or understanding the technicalities.
Example in our codebase
- How to clear the cache ?
- How to configure the logger ?
I liked the idea of separating our how to guides and explanations / tutorials, because sometimes you just want engineers to follow a specific flow without going too much in depth.
Diataxis was fantastic. It took a bit of effort to work out what the page titles were to cover everything we needed, but then when you were writing a page it was glorious.
It was so clear what you were saying and what "voice" you were writing in. If it's a Reference page you're all descriptive, with diagrams and bullet points. When it's a guide you're more discursive, but you know you're just imparting information not trying to teach. It made it so much easier to be coherent and clear about everything.