Hey, nice work. I think dedicating time and effort to documentation pays off in years to come.
Also -- from your original plug about your product I would have ignored it, but after reading through some of the docs, I actually see some use cases for this in a couple of upcoming projects!
What I'm about to say is a big topic that's probably better suited as a blog post, but I'll try anyways.
I think Diataxis is a valuable aid for thinking 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.
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.
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 modes of documentation.
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.
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?
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.
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.
[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
Diataxis is a great way of thinking about documentation and it really helps organizations get documentation off of the ground.
I generally didn't make separate pages for each type of documentation, they were separate sections.
For example, for a particular feature I would have an explanation at the top so someone looking at it would know what it was for, the audience would be a prospective customer/user trying to determine if they want/need to use it to do a task.
A tutorial section for someone who's never used it before, so very detailed.
A How-to section that has a easy to skim format so if someone is doing something but they can't remember all the steps they can go through it really quick to do the task so they can continue with their work.
The reference section would call out all the options and variables and prerequisites and so on.
For on-prem software the whole install and config section was a tutorial by default because they'd never done it before. A README should have two sections an explanation (what is it and what do you use it for) and a tutorial (how to set it up).
Tutorials are often in a separate section because people expect that but tutorials have an audience that have no experience in the product, the big problem is that the writer often has the curse of knowledge and has a hard time remembering what other people don't know and making sure to add that information in. They need to set up the framework to understand the design philosophy of the product so they can understand the How-tos.
I always want to jump right to the explanation documentation. The rest of it seems like a waste of time (well, the Reference bit can be somewhat useful later). I find tutorials and HOWTOs as misleading at best.
Well, that's your preference, it's definitely not everyone's. But you too would benefit from the explanation documentation being clearly labelled as such, so you can go there and avoid tutorials.
iamwpj|1 year ago
Also -- from your original plug about your product I would have ignored it, but after reading through some of the docs, I actually see some use cases for this in a couple of upcoming projects!
kaycebasques|1 year ago
I think Diataxis is a valuable aid for thinking 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.
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.
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 modes of documentation.
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.
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?
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.
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.
[1] https://pigweed.dev/seed/0102.html
[2] https://app.slack.com/client/T0299N2DL/C02149LN2HJ
[3] https://pigweed.dev/pw_rpc/ for on example, https://pigweed.dev/pw_async2/ for another
[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
[5] https://diataxis.fr/map/
[6] https://diataxis.fr/complex-hierarchies/
GarnetFloride|1 year ago
I generally didn't make separate pages for each type of documentation, they were separate sections.
For example, for a particular feature I would have an explanation at the top so someone looking at it would know what it was for, the audience would be a prospective customer/user trying to determine if they want/need to use it to do a task.
A tutorial section for someone who's never used it before, so very detailed.
A How-to section that has a easy to skim format so if someone is doing something but they can't remember all the steps they can go through it really quick to do the task so they can continue with their work.
The reference section would call out all the options and variables and prerequisites and so on.
For on-prem software the whole install and config section was a tutorial by default because they'd never done it before. A README should have two sections an explanation (what is it and what do you use it for) and a tutorial (how to set it up).
Tutorials are often in a separate section because people expect that but tutorials have an audience that have no experience in the product, the big problem is that the writer often has the curse of knowledge and has a hard time remembering what other people don't know and making sure to add that information in. They need to set up the framework to understand the design philosophy of the product so they can understand the How-tos.
riffic|1 year ago
ChrisArchitect|1 year ago
Diátaxis – A systematic approach to technical documentation authoring
https://news.ycombinator.com/item?id=42325011
cbsmith|1 year ago
SideburnsOfDoom|1 year ago
kreetx|1 year ago