Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt

Use this file to discover all available pages before exploring further.

One of the most common documentation problems is that information is hard to find. A page that tries to teach a concept while also explaining how to complete a task and listing configuration options is harder to understand than three separate pages that each serve a single purpose. 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 more effective.

​
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 categories can be as rigid as you need them to be. If it’s helpful to strictly label and categorize your content, do it. But if it’s too constraining and you need flexible content types, that works. What matters is that you know what each page is trying to accomplish. What is your user’s goal when they read a page? And how does the page help them accomplish that goal?

​
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.

​
Categorize 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 content around what users are trying to accomplish, and how to use Mintlify’s navigation primitives correctly.