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.
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.
Ugh, I don't like that page and I have actually deleted it. It'll be gone soon.
There is a real problem there, and that page doesn't do a good enough job of dealing with it. I have something cooking that is much, much better.
I urge people to not read this. Once you do, you will see all documentation will as the flawed and confusing mess it is. Ignorance is bliss!
truly. its the kind of thing that makes docs people justify their jobs rather than coming from a founder or user centric pov
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.
Agreed, a couple months back, I got cf to crawl the site and created a block of skills around it for personal use.
same, it’s great for first pass LLM docs
Posted many times. Here's the most recent time from 2024 (also has most discussion).
https://news.ycombinator.com/item?id=42325011
How is this different from Divio's documentation system?: https://docs.divio.com/documentation-system/
Update: https://diataxis.fr/colophon/#origins-and-development (Divio came first).
Perhaps add "A systematic approach to technical documentation authoring" to the title?
Diataxis + ADRs + C4 = The holy trinity of docs