We fixed our documentation with the Diátaxis framework(blog.sequinstream.com) |
We fixed our documentation with the Diátaxis framework(blog.sequinstream.com) |
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!
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
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.
What I'm hinting at re: homepages and READMEs is that there's an art and science to index pages (I think of both READMEs and homepages as types of index pages). I'm not convinced that you can boil down index pages to just a mix of explanations, tutorials, references, and guides. I think it's a different type of content that's not really well-represented on the Diataxis map.
Diátaxis – A systematic approach to technical documentation authoring
I just hadn't really appreciated why other people wanted different kinds of documentation. I always feel like if I don't understand the "why" I really don't know the tool and therefore shouldn't use it until that was addressed.
If the “Hello World” tutorial for a new language takes 3 hours and downloading 15 GBs of files before you can start, maybe you’ll look at something else.
What I find for me, and what I think is really common, is that a longwinded "why" is not the right place to start - it's too dry, not practical, and I can bounce off it without understanding.
Starting with a demo, a "you can use this tool to do xyx in 5 lines of code, here's how" makes me see that it has value, to get a basic feel for it. And once that is in place I get that it has value - it's like a hook to hang the "explanation" on.
Then the reference is useful later, when you're somewhat familiar, but need to check a specific thing that you don't know yet. You don't need or want to read a long multi-paragraph explanation to confirm a technical "yes or no" question.
The reference is relevant to me too, though modern information retrieval tools make it much less so, as I can often get the reference information I want in context. The main reason the reference is helpful is that explanations often aren't as precise as you need them to be about the specifications for the tool.
In retrospect, I do get some value out of tutorials & HOWTOs, mostly as a check on my understanding. They're just not where I want to start.
I think a good way of framing it is that a lot of documentation these days starts with "getting started", and I've observed that more often than not, that actually makes everything more difficult. If I understand the tool first, I avoid going down a lot of blind alleys and misinterpretations. I have observed that people often use a tutorial or a HOWTO as a way to get something done quickly without ever reaching that understanding, but the reality is the understanding is reason you wanted a human using the tool in the first place.