mintlify__docs/guides/content-types.mdx

---
title: "Content types"
description: "Choose the right content type for your documentation goals."
keywords: ["Diátaxis", "tutorials", "how-tos", "reference", "explanation", "categorization"]
---

<Tip>
  This page explains different content types, when to use each one, and how to approach writing for each type.
</Tip>

Documentation should be organized around the specific goal you're trying to help people achieve. 

## Categorize using the Diátaxis framework

The [Diátaxis framework](https://diataxis.fr) is a helpful guide for categorizing content based on your audience's needs. Documentation can generally be mapped into one of these types:

1. Tutorials: Learning-oriented content for new users
2. How-to guides: Task-oriented guidance for specific problems
3. Explanations: Understanding-oriented conceptual discussions
4. Reference: Information-oriented technical descriptions

Defining content types helps you plan documentation with a clear purpose and makes it easier for users to find what they need.

<Frame>
<img src="/images/guides/best-practices/diataxis.webp" alt="A diagram of the Diátaxis framework showing four quadrants that correspond to the four content types: Tutorials, How-To Guides, Reference, and Explanation." />
</Frame>

## Picking a type

| Question                     | Tutorial             | How-To               | Reference            | Explanation          |
|:-----------------------------|:---------------------|:---------------------|:---------------------|:---------------------|
| What is the user's goal?      | Learn through practice | Solve a specific problem | Find precise information | Understand concepts |
| What is the user's knowledge? | Beginner             | Intermediate         | Experienced         | Any level           |
| What is the primary focus?    | Learning by doing    | Achieving a goal     | Providing information | Deepening understanding |
| How is the content structured? | Step-by-step        | Problem-solution     | Organized facts     | Conceptual discussions |
| Is it task-oriented?          | Yes, guided tasks    | Yes, specific tasks  | No, informational   | No, conceptual      |
| Is it designed for linear progression? | Yes | No | No | No |

## Writing for each type

### Tutorials (Learning-oriented)

- **Audience goal**: Learn something new through step-by-step instructions.
- **Characteristics**: Sequential and assumes no prior knowledge.
- **Writing approach**:
  - Set expectations of what the user will achieve after reading.
  - Use clear, incremental steps. Minimize choices that need to be made by the user.
  - Point out milestones along the way.
  - Minimize theory and focus on concrete actions.

### How-To Guides (Problem-oriented)

- **Audience goal**: Perform a specific task correctly.
- **Characteristics**: Goal-driven and assumes some prior knowledge.
- **Writing approach**:
  - Write from the perspective of the user, not the product.
  - Describe a logical sequence and omit unnecessary details.
  - Minimize context beyond what is necessary.

### Reference (Information-oriented)

- **Audience goal**: Find details about a product's functionality.
- **Characteristics**: Unambiguous, product-focused, scannable.
- **Writing approach**:
  - Be scannable and concise.
  - Prioritize consistency.
  - Avoid explanatory content. Focus on examples that are easy to copy and modify.

### Explanation (Understanding-oriented)

- **Audience goal**: Expand general understanding of a concept or highly complex feature.
- **Characteristics**: Theoretical, potentially opinionated, broad in scope.
- **Writing approach**:
  - Provide background context, such as design decisions or technical constraints.
  - Acknowledge opinions and alternatives.
  - Draw connections to other areas in the product or industry.

## Tips and tricks

1. **Maintain purpose**: Before writing, assign each page a specific content type and make it top of mind in the doc throughout your writing.
2. **Consider content freshness**: Regardless of content type, try to optimize for evergreen documentation. If something represents a moment in time of what a feature looks like on a specific date, it's probably better suited for a changelog or blog post than in your documentation. Or if something changes very frequently avoid putting it in your docs.
3. **Think like your users**: Consider different user personas when organizing content. See [Understand your audience](/guides/understand-your-audience) for more information.
4. **Use templates**: Start with [content templates](/guides/content-templates) that provide the basic structure for each content type.

While the Diátaxis framework provides a starting point, successful documentation requires contextual adaptation to your product. Start by understanding the framework's principles, then adjust them to serve your users' needs.

## Related pages

<CardGroup cols={2}>
  <Card title="Content templates" icon="file-code" href="/guides/content-templates">
    Copy and modify templates for each content type.
  </Card>
  <Card title="Style and tone" icon="pen" href="/guides/style-and-tone">
    Write effective documentation with consistent style.
  </Card>
  <Card title="Understand your audience" icon="users" href="/guides/understand-your-audience">
    Research and define your documentation audience.
  </Card>
  <Card title="Navigation" icon="compass" href="/guides/navigation">
    Organize your documentation structure effectively.
  </Card>
  <Card title="Improve your docs" icon="chart-line" href="/guides/improving-docs">
    Use data and metrics to improve documentation.
  </Card>
</CardGroup>