Comment by jamilbk
1 day ago
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.
> read the website beginning to end before starting
Huh. The “Start here” page says exactly the opposite. It's literally the first two sentences on the page:
> You don’t need to read everything on this website to make sense of Diátaxis, or to start using it in practice. In fact I recommend that you don’t.
So what makes you recommend reading it all first?
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.
Is there some way for me to be notified when you do? I don't see any RSS on your site.
The docs I have built up are at times too technical for users and not detailed enough for developers. I am not sure if it's a skill issue on my part for an individual piece of text, a skill issue on my part in applying the principles outlined by Diataxis, or a fault in the framework itself (or its self-documentation).
We're currently in the process of restructuring our documentation and I'd be very interested in an early draft of this, fully understanding that caveat emptor. Is it published anywhere currently?
Please post some kind of visible change notification (and something here) when you do!
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!