I was pretty sure the Divio version came first, so I wasn’t sure about this Diátaxis thing. However:
Both sites are Sphinx documentation built from GitHub repositories; the Divio repo is listed as a fork of the Diátaxis one
The Diátaxis site says “The Diátaxis Documentation Framework is the work of Daniele Procida” and the Divio site does not say that… but the Divio site does link to a 2017 PyConAU talk about the system, presented by… Daniele Procida
I’m guessing Procida developed this independently, then got hired by Divio, who adopted it?
Thanks for pointing it out, but it’s absolutely fine! I used to work at Divio, which is where Diátaxis started life. https://documentation.divio.com has been around for years, and predates https://diataxis.fr.
Diátaxis is a good starting point but in my experience has a big problem: people try to cram all documentation into the 4doc model. It’s good for a library, but if you’re documenting programming languages or really advanced tooling, you need progressive lessons and worked examples, which don’t fit neatly into the model. Worst case people will leave that out instead of break the model.
Less serious, but more personally annoying, is when the how-tos don’t match actual common use cases. Like one language I know of has “how to create a github repo” with the language and “how to visualize the current database”, but not “how to read a file” or “how to get the date.”
Wow this is a really nice (on the surface at least - I’ve just skimmed for now)!
When I’m done my current contract I’m definitely going to look out for a tech writer job. I just love teaching and learning this way - feels more rewarding than pumping out code.
AKA, the divio documentation system but without the divio.
We use it, it’s a nice way of organizing existing docs, but an even better way to design docs.
I was pretty sure the Divio version came first, so I wasn’t sure about this Diátaxis thing. However:
I’m guessing Procida developed this independently, then got hired by Divio, who adopted it?
https://github.com/evildmp/diataxis-documentation-framework/issues/14#issuecomment-1170838014
Diátaxis is a good starting point but in my experience has a big problem: people try to cram all documentation into the 4doc model. It’s good for a library, but if you’re documenting programming languages or really advanced tooling, you need progressive lessons and worked examples, which don’t fit neatly into the model. Worst case people will leave that out instead of break the model.
Less serious, but more personally annoying, is when the how-tos don’t match actual common use cases. Like one language I know of has “how to create a github repo” with the language and “how to visualize the current database”, but not “how to read a file” or “how to get the date.”
Wow this is a really nice (on the surface at least - I’ve just skimmed for now)!
When I’m done my current contract I’m definitely going to look out for a tech writer job. I just love teaching and learning this way - feels more rewarding than pumping out code.