Diataxis sorts documentation into four forms that match four reader needs: tutorials, how-to guides, technical reference and explanation. A page that tries to be all four answers none well. Separating them also gives every page a single, clear question, which helps people and any system that retrieves it.
The four types
The Diataxis site names the four forms and says they correspond to four distinct needs.
- Tutorials teach a beginner by walking through a complete, end to end experience.
- How-to guides help a competent user reach a specific goal.
- Reference describes the product accurately and completely.
- Explanation gives background and reasoning.
What the how-to guide rules say
The Diataxis how-to page states that tutorials and how-to guides are wholly distinct, because they serve different needs. It lists principles worth borrowing:
- Focus on the user's goal, not the tool's operations.
- Action only. Leave out digression and teaching, and link to explanation or reference instead.
- Prioritize usefulness over completeness.
- Order steps to match how the user thinks.
- Name the title precisely, so it says exactly what the guide shows.
Why this helps findability
A person types a question. A page titled for that exact task, with the answer first, matches it. A page titled "Overview" that mixes install steps, flags and philosophy matches nothing in particular.
Google's title guidance says each page should have a distinct, descriptive title and that near identical titles across many pages make results hard to tell apart. Four page types with precise titles solve that naturally. See page titles and meta descriptions.
A working layout
- A landing page that links to all four sections.
- One tutorial per major audience.
- How-to guides named as tasks: "Rotate an API key", "Run a scan in CI".
- Reference generated from source where possible: flags, exit codes, config keys.
- Explanation pages for concepts and trade offs.
Cross link them with descriptive anchor text. Google's link guidance says to avoid generic text such as "click here" and to link related resources in context.
Audit your own docs
Pick ten pages and label each as one of the four. If you cannot decide, the page is probably doing two jobs. Split it, keep the old URL pointing at the main part, and redirect or link the rest. Handle moved URLs carefully, as in redirects and status codes for moved docs.
Quick check
Do I need all four types?
Not on day one. Most products need how-to guides and reference first, then add tutorials and explanation as the audience grows.
Is Diataxis a search ranking method?
No. It is a documentation framework. The search benefit is indirect, through clearer pages and titles.
Sources
- Diataxis documentation framework
- Diataxis, how-to guides
- Title links, Google Search Central
- Crawlable links, Google Search Central
Last reviewed: 19 October 2026.
