Skip to main content
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 content type before you write prevents this. It also gives AI writing tools a clear target.

​
Four content types

The Diátaxis framework defines four types of documentation based on what the reader needs: Use these categories as strictly or loosely as your team needs. What matters is that you can say what each page helps its reader accomplish.

​
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, the page stops matching what the reader came for. Someone who came to do something ends up reading an essay. Someone who came to understand something gets a list of parameters. Mixed pages also cause navigation problems. They’re hard to place in a 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.”
That prompt gives the tool a type, a reader, and a boundary, so the draft has one job.

​
Make content types a standing instruction

Instead of repeating content type rules in every prompt, add them to the same places as your reader definition: .mintlify/AGENTS.md for Mintlify’s agent, AI instructions for the editor’s agent, and the instruction files your local tools read.
.mintlify/AGENTS.md
With this in place, AI tools ask “which type is this page?” before they draft, and you can point to the rule when a draft drifts.

​
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. Keep the list. You’ll use it when you design navigation in a later lesson. Next up: Structure individual pages for scanning—turn a page goal into clear prerequisites, headings, examples, and verification.