Tutorials, Reference, How-To, Explanation: Structuring Docs with Diataxis

A confusing getting-started page usually isn't badly written — it's four documents wearing one costume. The Diataxis framework, created by Daniele Procida, sorts documentation into tutorials, how-to guides, reference, and explanation because each answers a different question a developer asks at a different moment. Mixing them produces pages that half-serve everyone and fully serve no one.

Quick Answer: Diataxis splits docs into four quadrants — tutorials (learning by doing), how-to guides (solving a specific task), reference (looking up facts), and explanation (understanding concepts) — each matched to a distinct developer mindset. A page that blends two quadrants degrades both.

What Is the Diataxis Framework, Exactly?

Diataxis is a documentation system built around a simple observation: developers approach docs in one of four mental modes, and each mode wants a fundamentally different kind of writing. Procida formalized it after years of technical writing at organizations including the Ubuntu project, and it has since been adopted by Django, Gatsby, Cloudflare, and dozens of other developer-facing products.

The framework organizes content along two axes: whether the reader is acquiring skill or applying it, and whether the content is practical (action) or theoretical (cognition). Cross those two axes and you get four quadrants:

Each quadrant has its own contract with the reader. A tutorial promises a working result at the end, even if the reader doesn't understand every step yet. A reference promises accuracy and completeness, even if it's boring to read linearly. Violating a quadrant's contract — say, a reference page that suddenly stops to explain why a rate limit exists — breaks the reader's trust in the document type itself.

Why the Two-Axis Model Matters More Than the Four Labels

The labels are memorable, but the axes are what make the framework actionable. A page fails Diataxis not because it's mislabeled but because it answers a question from the wrong axis — explaining theory to a reader who came to copy-paste a working code path, or handing exhaustive parameter tables to a first-time user who just wants a green checkmark.

This is also why Diataxis pairs naturally with a "docs as product" mindset rather than a documentation-as-afterthought one — see Docs as Product, Not Afterthought for how that reframing changes prioritization, not just structure.

Tutorials vs. How-To Guides: Learning vs. Doing

Tutorials and how-to guides are both action-oriented and both use numbered steps, which is exactly why they get confused with each other constantly. The difference is the reader's goal: a tutorial teaches a beginner through a guided journey with one guaranteed path, while a how-to guide helps a competent user accomplish a specific real-world task they already understand the shape of.

Tutorials are pedagogy, not documentation of a feature. A good tutorial:

1. Has exactly one path — no "or you could also..." branches that fork the learner's attention.
2. Guarantees a working result at each checkpoint, so the learner never wonders if they broke something.
3. Deliberately hides edge cases, error handling, and configuration options that would distract from the core concept being taught.
4. Builds confidence through repetition of a small pattern before introducing variation.

How-to guides assume competence and jump straight to the task. They answer "how do I rotate an API key" or "how do I paginate a large result set" — questions a developer only asks once they already understand the system's basic shape. A how-to guide can branch ("if using OAuth, do X; if using API keys, do Y") in ways a tutorial never should, because the reader is choosing their own path, not following a script.

The Getting-Started Page Is Where This Breaks Most Often

Most "Getting Started" pages try to be a tutorial and a how-to guide and a reference simultaneously — a guided first-run experience that also tries to document every auth method and every config flag along the way. The result reads like a tutorial for the first three steps, then abruptly becomes a reference table, then trails into an explanation of the underlying protocol. Nobody using it as a tutorial finishes it; nobody using it as a reference can find anything.

This split matters even more for the first fifteen minutes of a developer's experience — the window many teams now track deliberately, as discussed in Developer Time to First Call. A muddled getting-started page is often the single largest lever on that metric, because it's the one page every new developer is guaranteed to hit.

Reference vs. Explanation: Facts vs. Understanding

Reference material and explanation are both cognition-oriented — the reader isn't typing commands, they're thinking — but they answer opposite questions: reference tells you what is true, explanation tells you why it's true or why it matters. Conflating them produces reference pages bloated with rationale a lookup-mode reader will skip, and explanation pages diluted by tables a comprehension-mode reader doesn't need yet.

Reference material is defined by three properties:

• Structured — organized by the shape of the system (every endpoint, every parameter, every error code), not by narrative order.
• Complete — nothing is omitted because it seemed unimportant; a reference the writer edited for interest is no longer trustworthy.
• Terse — a developer mid-task wants the fact in under five seconds, not a paragraph of context around it.

Explanation material is defined by the opposite properties:

• Discursive — it can wander, connect ideas, and compare alternatives.
• Selective — it doesn't need to cover every case, only the ones that build understanding.
• Contextual — it answers "why does this API use cursor pagination instead of offset pagination" in a way a reference table never should.

An Audit Exercise: Mapping Your Docs to the Four Quadrants

Run this audit on any docs site with more than a handful of pages — it takes an afternoon and reliably surfaces the muddiest pages first.

1. List every page in a spreadsheet with columns for URL, title, and word count.
2. For each page, tag every section (not the whole page) with one of the four quadrant labels based on the question it's actually answering, not the page's title.
3. Flag any page where sections span three or more quadrants — these are your worst offenders and usually your highest-traffic pages, since "Getting Started" and "Overview" pages are exactly where teams cram everything.
4. Count quadrant coverage overall. A common failure pattern is heavy reference and tutorial content with almost no explanation — teams document what and how but never why, leaving architectural decisions undocumented anywhere.
5. For each flagged page, decide whether to split it into separate quadrant-pure pages that cross-link, or prune the out-of-place sections into an existing page of the correct type.

Reorganizing a Muddled Getting-Started Page: A Worked Example

A typical muddled getting-started page opens with an install command, jumps into "here's every auth method we support," drops in a full parameter reference table, then closes with a paragraph about the system's design philosophy. Every sentence is reasonable on its own; together they serve no single reader well.

The reorganization keeps one page as a true tutorial and extracts the rest:

• Tutorial (stays as "Getting Started"): one auth method only (the simplest, usually API keys), one guaranteed working call, one visible success result. No branching, no "advanced" callouts.
• How-to guide ("Authenticate with OAuth" / "Rotate API Keys"): every auth method the tutorial didn't cover, written for a developer who already succeeded once and now needs a specific variant.
• Reference ("API Reference"): the full parameter table, every endpoint, every error code — generated from the actual API surface rather than hand-maintained prose, so it never drifts out of sync with what's shipped.
• Explanation ("Why We Use Cursor Pagination" / "Authentication Model Overview"): the design-philosophy paragraph, expanded into its own page with room to actually make the argument.

The tutorial then links out to each of the other three at the natural moment a graduating reader would want them — after the first successful call, not before. This is the same instinct behind mapping documentation to actual developer intent rather than internal team structure, a pattern worth cross-referencing against Jobs to Be Done thinking: a developer's "job" during onboarding is narrowly "get one call working," not "understand the whole system."

How This Changes Docs Maintenance, Not Just Reading

Splitting quadrants also changes who owns what and how often it changes. Reference content should regenerate from source (OpenAPI specs, code annotations) on every release; explanation content changes rarely, only when the underlying design changes; tutorials and how-to guides change when the product surface a new developer touches first changes. Bundling all four into one page means every edit risks breaking a part nobody meant to touch — a maintenance cost that compounds as a docs site grows, which is part of why devtools PM roles increasingly treat documentation architecture as a product decision, not a writing-style preference.

Rolling Diataxis Into a Growing Docs Site

Adopting Diataxis on an established, sprawling docs site is a migration, not a rewrite — the framework works best applied incrementally to the highest-traffic, most-confused pages first rather than as a big-bang restructure. Start with the audit above, fix the top three offenders, and let the quadrant structure become the default for all new pages going forward.

Practical rollout guidance:

1. Pick quadrant-based navigation categories (Tutorials, Guides, Reference, Explanation) as top-level nav, so the structure is visible to readers, not just internal to your content model.
2. Template new pages by quadrant — a tutorial template, a how-to template, and so on — so contributors don't have to remember the rules each time; the template enforces them.
3. Treat reference as generated, not authored, wherever the underlying API or schema already exists as structured data, so it can't silently drift from what's actually true.
4. Revisit high-traffic pages first — analytics on which docs pages get the most visits (and the highest bounce or "was this helpful: no" rates) usually points straight at your worst quadrant-blending offenders.

This structural discipline compounds with other developer-experience investments. Teams thinking about bottom-up PLG motion through developers or optimizing the broader customer journey for technical buyers often find that docs structure is a bigger lever than any individual page's prose quality — a confused architecture undermines even well-written content.

Where Prodinja Fits Into a Diataxis Structure

Populating the reference quadrant is usually the least interesting work and the easiest to get wrong through manual drift — parameter tables and example calls that fall out of sync with what the API actually does the moment nobody's watching. Prodinja's API Designing tool is built to generate endpoint reference and curl examples directly from how you've modeled the API, so that quadrant of your docs structure can be populated and kept current without hand-transcribing it from source code. It doesn't replace the tutorial, how-to, or explanation writing — those genuinely need a human's judgment about audience and narrative — but it's designed to take the mechanical, error-prone part of reference maintenance off a writer's plate.

Key Takeaways

• Diataxis has two axes, not just four labels: learning-vs-applying, and action-vs-cognition. Understanding the axes is what makes the framework diagnostic rather than just a filing system.
• Tutorials guarantee one path and a working result; how-to guides assume competence and can branch — confusing the two produces pages that neither teach nor efficiently serve.
• Reference must be complete and terse; explanation can be selective and discursive — bundling them frustrates both the reader in a hurry and the reader trying to understand.
• Getting-started pages are the most common quadrant-blending offender because teams try to make one page do a tutorial's, reference's, and explanation's job at once.
• Run the audit exercise on your highest-traffic pages first — tag sections (not whole pages) by quadrant, and split or prune anything spanning three or more.
• Generated reference content stays accurate; hand-maintained reference content drifts — tooling that produces reference material from your actual API model reduces that drift risk structurally.