| We just applied this framework to the Sequin [1] docs two weeks ago. It has felt so nice to have a framework. I think our docs flow really well now, and it's been easier for us to add and maintain docs because we know where to put things. The slightly ironic part is that the Diataxis docs themselves are a bit obtuse. It's a little verbose. So it took a couple passes for it all to click. The analogy I gave my team that was helpful for everyone's understanding: Imagine you're shopping for a piece of cooking equipment, like a pressure cooker. The first thing you're going to look at is the "quickstart" (tutorial) – how does this thing work generally? You just want to see it go from A to B. Then, you're going to wonder how to use it to cook a particular dish you like. That's a how-to. If you're really curious about anything you've seen so far, then you'll flip to the reference to read more about it. For example, you might check the exact minutes needed for different types of beans. And finally, when you're really invested in pressure cooking and want to understand the science behind it - why pressure affects cooking times, how the safety mechanisms work, etc. - that's when you'll read the explanatory content. Comically, our docs were completely backwards: we lead with explanation ("How Sequin Works"). I think that's the natural impulse of an engineer: let me tell you how this thing works and why we built it this way so you can develop a mental model. Then you'll surely get it, right? While that may be technically accurate, a person doesn't have the time or patience for that. You need to ramp them into your world. The quickstart -> how-to -> reference flow is a great way to do that. Then if you really have their attention, you can galvanize them about your approach with explanatory material. [1] https://sequinstream.com/docs PS: If you have any feedback on our docs, lmk :) |
Minor note: The only thing in your docs that made me pause was the repeated use of "CDC", which I had to google the definition of. (For context, I have implemented "CDC" several times in my career, but wasn't familiar with the acronym)