Documentation content types

Choose the right documentation type for each page using the Diátaxis framework: tutorials, how-to guides, reference, and explanation.

Not all documentation serves the same purpose. A tutorial that walks a new user through their first deployment is fundamentally different from an API reference a developer consults every day. Mixing these purposes in a single page creates content that serves neither goal well.

The Diátaxis framework provides a practical system for categorizing documentation by the user's need in the moment.

The four documentation types

Tutorials (learning-oriented)

Tutorials teach through doing. The user's goal is to learn something new, and the tutorial's goal is to give them a successful experience—not to document every option or explain every detail.

A good tutorial:

• Assumes no prior knowledge of the specific task
• Takes the user through one complete, working example from start to finish
• Minimizes choices—tell users exactly what to do rather than offering alternatives
• Marks progress at meaningful milestones ("You've now configured authentication")
• Explains just enough to keep the user moving, not everything there is to know

Tutorials are the highest-investment content type to write and maintain, but they have an outsized impact on whether new users succeed with your product.

How-to guides (task-oriented)

How-to guides help users accomplish a specific goal. Unlike tutorials, they assume the user already has some context and wants to do a particular thing, not learn a concept.

A good how-to guide:

• Addresses one specific task in the title and throughout
• Assumes prior knowledge of the prerequisites
• Provides a clear sequence of steps without unnecessary context
• Describes what to do, not how the system works underneath

The distinction from tutorials matters in practice: a tutorial on "Getting started with authentication" walks a new user through the whole process step by step. A how-to guide on "Rotate your API keys" assumes the user knows what API keys are and just needs the steps.

Reference (information-oriented)

Reference documentation describes the system accurately and completely. Users consult it to look something up—they aren't reading sequentially, and they aren't learning.

Good reference documentation:

• Prioritizes completeness and accuracy above all else
• Is scannable: tables, consistent formatting, short descriptions
• Avoids explanatory or conceptual content
• Documents everything, including defaults, limits, and edge cases
• Stays close to the structure of what it documents (an API reference follows the API's structure)

API references, configuration option lists, and CLI command references are all reference content.

Explanation (understanding-oriented)

Explanations deepen understanding of a concept. Users read them when they want to understand why something works the way it does, not how to do a specific task.

Good explanation content:

• Addresses the context and motivation behind a design decision
• Acknowledges tradeoffs and alternatives
• Connects concepts across the broader system
• Takes opinionated positions where appropriate

Architecture overviews, concept guides, and "how X works" pages are all explanation content. They're distinct from how-to guides in that a reader finishing an explanation article shouldn't feel instructed to do something—they should feel they understand something better.

Choose the right type for each page

When in doubt about which type fits a page, ask: "What does the user do after reading this?" If they've completed a task, it's a how-to or tutorial. If they now understand something and may go on to take action elsewhere, it's an explanation. If they've looked up a specific detail, it's reference.

Writing for each type

Writing tutorials

Set expectations at the start: what do users build or accomplish by the end? Use <Steps> components for sequential progress and celebrate completion at natural milestones. Minimize decisions—where there are multiple valid approaches, pick one and say so.

Writing how-to guides

Lead with the task in the title: "How to configure webhooks," "How to migrate from v1 to v2." Write from the user's perspective, not the product's. Skip context that does not affect the steps. Link to explanation or reference content for users who want to understand more.

Writing reference

Structure reference docs around the thing you describe, not around user journeys. Use consistent formatting across all entries. Every parameter, flag, or option should have a type, default value, and one-line description. Keep it scannable.

Writing explanation

Start with the question you're answering. For example, ask "Why does authentication work this way?" or "What's the difference between organizations and workspaces?" Acknowledge that multiple approaches exist. Explain why the product makes its choices. Link to how-to guides for users who want to act on what they've learned.

Tips for maintaining type consistency

• Assign a content type before writing. Deciding in advance shapes every other writing decision, including structure, length, tone, and what to include or exclude.
• Review mixed-purpose pages. Pages that explain a concept, include a tutorial, and reference a list of options all at once are hard to maintain. They are also hard to use. Split them or pick a primary type.
• Adapt the framework to your product. Diátaxis is a starting point, not a rigid rule. Products with unusual structures may need hybrid approaches. The underlying principle—match content to the user's need in the moment—applies universally.