5 ms·
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
by jamilbk 2mo 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/ 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.
- DanieleProcida 2mo agoUgh, 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.
- LoganDark 2mo agoIt 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!
- nlawalker 2mo agoPlease post some kind of visible change notification (and something here) when you do!
- mstade 2mo agoWe'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?
- zenoprax 2mo agoIs 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).
- DanieleProcida 1mo agoAt your request, https://diataxis.fr/atom.xml https://diataxis.fr/atom.xml
- macartain 1mo agoSo its now 404'ing?
- zahrevsky 2mo ago> 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?