Skip to main content
One of the most common documentation problems isn’t missing information — it’s information in the wrong container. A page that tries to teach a concept while also explaining how to complete a task and listing configuration options will do all three things poorly. Users who want to do the task have to wade through the explanation. Users who need the configuration details have to read through the steps. Nobody gets what they came for quickly. Choosing the right content type before you write solves this. It also makes AI tools dramatically more effective.

​
The four content types

The Diátaxis framework defines four types of documentation based on what the reader needs:
TypeReader’s goalExamples
TutorialLearn by doing”Build your first integration”
How-to guideComplete a specific task”Set up webhooks”
ReferenceLook up specific informationAPI endpoint parameters
ExplanationUnderstand a concept”How our authentication model works”
These aren’t rigid categories — they’re lenses. The question isn’t which box a page fits into perfectly, but which goal it primarily serves.

​
Why mixing types causes problems

Each content type has a different structure, a different level of assumed knowledge, and a different relationship to other pages. Tutorials are sequential and assume nothing. How-to guides assume the reader knows what they’re doing and just need the steps. Reference material is scannable, not readable. Explanations are the only type where depth and context are the point. When you mix them, you break the contract the reader has with the page. They came to do something and ended up reading an essay. Or they came to understand something and got a list of parameters. Neither experience builds trust. The navigation consequences are real too. Mixed-type pages are hard to place in a logical hierarchy because they don’t clearly belong anywhere.

​
The AI problem with content types

AI writing tools don’t default to any particular content type. Given a prompt like “write documentation for our webhook feature,” most AI tools will produce a hybrid: some explanation, some steps, some reference material, blended together. It reads fine, but it serves no reader particularly well and creates navigation headaches down the line. The fix is to be explicit. AI tools respond well to content type instructions:
“Write a how-to guide for setting up webhooks. Assume the reader already knows what webhooks are and has already authenticated. Focus only on the steps. No background explanation.”
This produces something far more useful than a generic prompt.

​
Enforce content types in your Mintlify tooling

If your team uses Claude Code, Cursor, or similar AI tools to maintain docs, you can codify content type rules so AI applies them consistently. Add a section to your CLAUDE.md or Cursor rules file in your Mintlify repository: 
## Content types

Every page is one of four types: tutorial, how-to, reference, or explanation.

- **Tutorials**: Sequential, assumes no prior knowledge, focused on learning by doing
- **How-to guides**: Goal-driven, assumes prior knowledge, focused on completing a task
- **Reference**: Scannable and complete, no explanatory prose
- **Explanations**: Conceptual, provides background and context, not task-oriented

Identify the content type before writing or editing any page. Do not mix types on a single page. If a how-to guide needs to explain a concept, link to an explanation page instead of including the explanation inline.
This means every AI-assisted edit to your docs starts from the right frame.

​
Categorizing what you already have

If you’re working with an existing Mintlify site, start with an audit. Go through your highest-traffic pages and assign each one a content type. You’ll likely find:
  • Pages doing multiple jobs that need to be split
  • How-to guides buried inside reference pages
  • Tutorials that assume too much prior knowledge
  • Explanations that never get read because they’re positioned as onboarding content
Don’t try to fix everything at once. Start with the pages that get the most traffic and generate the most support questions — these have the most impact when improved. Once you’ve categorized your existing pages, use that map to inform how you organize your Mintlify navigation. Pages of the same type often belong together, and separating tutorials from reference material is one of the clearest wins you can make for discoverability. Next up: Design navigation for your users, not your product — how to organize docs around what users are trying to accomplish, and how to use Mintlify’s navigation primitives the right way.