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).
Diátaxis
11–20 of 66 posts
Re: Diátaxis
#12We 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.
Re: Diátaxis
#13We 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://dia…
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.
Re: Diátaxis
#14I 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!
Re: Diátaxis
#15How 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).
Same fundamental ideas, but I got a lot of things wrong in that earlier version (which is several years old now).
Re: Diátaxis
#16Diataxis + ADRs + C4 = The holy trinity of docs
I had to search these terms, does ADR mean ‘Architecture decision record’ and C4 the ‘C4 model’? How do you combine them in documentation?
Re: Diátaxis
#17I'd like to take advantage of the attention it's getting to point out that I am working on translating Diátaxis into other languages https://diataxis.fr/translation/, and you can see an in-progress version with some partially completed translations at https://diataxis-translated.readthedocs.io/translation/.
Re: Diátaxis
#18Another 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.
Re: Diátaxis
#19We 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://dia…
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.
It makes sense to me (I agree with it), but I also agree that it doesn't really deal with it. I look forward to whatever you're cooking!
Re: Diátaxis
#20Another 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.