What I'm about to say is a big topic that's probably better suited as a blog post, but I'll try anyways.<p>I think Diataxis is a valuable aid for <i>thinking</i> about documentation strategy but is not always necessarily a literal blueprint. I.e. when determining whether you have completely documented an area, it's very valuable to ask yourself "do we have tutorial content for this area? Explanations? References? Guides?" but it doesn't necessarily mean that the tutorial and explanations need to literally be on different pages.<p>We tried adopting Diataxis on pigweed.dev [1] as a literal blueprint and it resulted in too much fragmentation. E.g. the explanations for a Pigweed module were on one page, but the tutorial was on another. Users and teammates found it annoying to have to jump back-and-forth so much. In my mind, I still use Diataxis as an internal checklist of sorts, but I don't necessarily require the content to be split across different pages. E.g. sometimes the most natural/effective place to put an explanation is in a tutorial, when the user is getting hands-on experience with that topic. You reinforce the theoretical foundations with the direct experience and vice versa. If you only link to explanations from the tutorial, some (most?) users won't click those links, and therefore may never get exposed to the theoretical foundations. For some areas that's OK; for others it's could be a disservice to the user. It depends strongly on what you're documenting.<p>I believe I have discussed this with Daniele on the Diataxis channel in Write The Docs Slack [2] and they responded that this is why they call it <i>modes</i> of documentation.<p>That said, these recently updated docs [3] reflect our general approach to Pigweed module documentation [4]. You can see that we still do often split our docs clearly along the lines of references/guides/explanations/tutorials.<p>The other big limitation of Diataxis IMO is that I'm not sure if the map [5] really is a comprehensive way to think about documentation. (As I've said in previous HN discussions about Diataxis) How do homepages and READMEs fit into the map, for example?<p>That said, the world's documentation is much better off thanks to Diataxis. The fact that it gets discussed a few times every year here on HN is a great service because it makes the task of improving documentation much less daunting and much more straightforward, and provides very focused discussion on how to improve documentation strategy in general.<p>Update: I think [6] is a newer document (published Aug 2023) that has been added to cover the complexities I mentioned in this comment. This page was not on my radar.<p>[1] <a href="https://pigweed.dev/seed/0102.html" rel="nofollow">https://pigweed.dev/seed/0102.html</a><p>[2] <a href="https://app.slack.com/client/T0299N2DL/C02149LN2HJ" rel="nofollow">https://app.slack.com/client/T0299N2DL/C02149LN2HJ</a><p>[3] <a href="https://pigweed.dev/pw_rpc/" rel="nofollow">https://pigweed.dev/pw_rpc/</a> for on example, <a href="https://pigweed.dev/pw_async2/" rel="nofollow">https://pigweed.dev/pw_async2/</a> for another<p>[4] I'm well aware that some docs on the site are in bad need of an update, so please don't grab some random page from the site and tell me that the pigweed.dev docs suck and therefore everything I say is invalid<p>[5] <a href="https://diataxis.fr/map/" rel="nofollow">https://diataxis.fr/map/</a><p>[6] <a href="https://diataxis.fr/complex-hierarchies/" rel="nofollow">https://diataxis.fr/complex-hierarchies/</a>