Better documentation with the Diátaxis Framework
Jack breaks down the Diátaxis documentation framework — the four-part system (tutorials, how-to guides, reference, explanation) he used to restructure his own docs in his first week at a new DevTools job — plus what Sequin and Logdy got right applying it.
This is a different kind of episode. Jack just joined an early-stage DevTools startup to work on documentation, and needed a framework fast — he remembered Matt Palmer from Replit recommending the Diátaxis documentation framework, and spent his first week applying it to his own team's docs.
In place of an interview, this one walks through what Diátaxis actually is, in creator Daniele Procida's own words, how two real companies — Sequin and Logdy — have applied it, and what Jack learned restructuring his own docs around it.
The Q&A below is experimental — extracted from the episode transcript with AI. If you spot a mistake, let us know at jack@scalingdevtools.com.
What is Diátaxis, in short?
It's a free, systematic approach to technical documentation from Daniele Procida, a core developer on Django. It says there are four types of content in your docs: tutorials, how-to guides, explanation, and reference. Reference is the easiest to picture — your API reference docs, your SDK reference, just stating exactly how something is. Explanation is fairly straightforward too — it's not solving a specific problem, more helping you understand something in general, like explaining how voice AI pipelines work broadly. The two that trip people up are tutorials and how-to guides — before this, if you heard "tutorial," you'd probably assume that's the same thing as a how-to.
What's the actual difference between a tutorial and a how-to guide?
In Daniele's own words: "A tutorial is a lesson — a lesson that takes the reader by the hand through a series of practical steps to realize a project or complete a meaningful exercise. The only way one learns a new skill is by doing. Tutorials are learning oriented... Your tutorial must be repeatable, must instill confidence, must result in success every time for every learner." A how-to guide, by contrast, "takes the reader through the steps required to complete a specific task. How-to guides are recipes... task oriented or problem oriented. It serves not the beginner, but the already competent user. It responds to a question — how do I do such and such — with a series of actions and only actions, without digressions or explanations or attempts to teach." Tutorials and how-to guides are similar because they're both about practical steps; how-to guides and reference are similar because they both serve you while you're actually working; reference and explanation are similar because they're both about theoretical knowledge; and explanation and tutorials are similar because both serve your study of the subject.
How did you actually apply this to your own docs in your first week?
I lifted the structure almost exactly onto docs.layercode.com: one "Start Here" section for getting started, then four more columns — tutorials, how-to guides, reference, and explanations. Tutorials became things like "get started with Next.js," "get started with Hono," "get started with FastAPI" — I didn't write new content, I just renamed and moved what already existed, and since the docs weren't indexed by Google yet, I didn't have to worry about redirects. How-to guides are short and task-specific — "integrating Layer Code with Twilio" walks through exact steps: go to the dashboard, open client settings, enable Twilio phone calls, save changes — nothing extra, no teaching along the way. Reference covers the API and SDK references, and explanations cover things like how turn-taking works in voice AI. Before, the docs were just organized by area — front end, back end, telephony — and this feels a lot clearer.
What did Sequin get right applying Diátaxis to their docs?
Sequin posted on Hacker News about applying the framework, saying it's felt so nice to have one — their docs flow better now and are easier to maintain because they know where things belong. One analogy their team used internally that I love: imagine shopping for a pressure cooker. First you look at the quick start, the tutorial, to see how it works generally. Then you want a how-to for cooking a specific dish. If you're curious about something specific, you flip to the reference — say, exact minutes for different bean types. And finally, once you're really invested, you read the explanatory content about why pressure affects cooking time and how the safety mechanisms work. Comically, their docs used to be backwards — they led with explanation, because that's the natural instinct of an engineer: let me tell you how this works and why we built it this way. But a reader doesn't have the patience for that up front — you need to ramp them in with a quick start, then a how-to, then reference, and only bring the explanatory material once you've earned their attention. On the site itself, Sequin has a "Getting Started" section with quick starts for different data streams, a section explaining their managed offering, setup guides, and a "How To" section — though a couple of things filed under "how to," like "deploy to production," read like they used to be tutorials.
What about Logdy?
Logdy has sections for introduction, tutorial, explanation, and reference — I don't see a "how-to guides" section, which is interesting. And unlike the pressure-cooker advice about leading with the quick start, Logdy actually leads with "what is Logdy" first, which makes me curious whether that was a deliberate choice. Their tutorials cover things like Docker logs and the web UI; their explanation section covers things like following logs, command modes, and trace visualization.
Is Diátaxis a cure-all?
No, and the Hacker News discussion around it makes that clear. One technical writer pointed out that a rigid four-category system can miss what users actually need if the same information has to live in more than one place — in a UI, a docs portal, and a mobile app, for instance — which is called content reuse, and doing UX research up front avoids feeling boxed in by an overly restrictive model later. My favorite comment, the one that actually made it click for me, was simpler: tutorials are for learning by doing, guides are for solving specific problems, references are for quick lookups, and explanation is diving into the why. The real value of Diátaxis is less about the four rigid categories themselves and more that it shifts your focus from trying to cram everything into one perfect document to recognizing that different users have different needs — sticking too rigidly to any system is the trap. Someone else who's met Daniele in person said they like the idea but have reservations about how rigidly it can get enforced during a sprint; as long as it's not treated as total dogma, it's a great tool for deciding how to produce documentation.
If you don't want to overhaul all your docs at once, what does Diátaxis actually suggest you do?
Don't try to implement the whole thing in one go. The suggested workflow is: look at whatever documentation is in front of you right now — even if that's literally nothing yet — ask if there's any way it could be improved, decide on one thing you could do right now, however small, that would improve it, do that thing, then repeat. You don't need to buy into the full theory or read the extended write-up to get value, and there's no final state you're required to reach — even one small improvement is worth something, and in practice, each thing you do gives you a clue as to the next thing to do.