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.
I checked out your docs, and I agree that they flow very nicely! So often it seems that docs are either frustratingly vague to the point where it almost seems like the company is embarrassed to admit that their tool is a tool and not a "transformative synergy experience" (or similar nonsense), or docs immediately get overly specific without covering "why this product exists".
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)
In case you weren't already aware, most markdown parsers support actual HTML tags in it, and there's <abbr title="change data capture">CDC</abbr> that allows being visually succinct, is a11y friendly, and in most browsers is visually distinct to prompt the user there's more content hidden in the hover or long-press
I think having those four approaches is the key thing and you’re addressing it well. The flow is really the readers choice. My brain works in the way of wanting the overall explanation first. Then I seek the how-tos and tutorials.
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 :)