# Source: https://www.mintlify.com/docs/guides/content-types.md

> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Content types

> Choose the right content type for your documentation goals.

<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="https://mintcdn.com/mintlify/mgh6fYMQy9DM5E4a/images/guides/best-practices/diataxis.webp?fit=max&auto=format&n=mgh6fYMQy9DM5E4a&q=85&s=057c36ac97446a5d360871e41852520e" 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." data-og-width="1920" width="1920" data-og-height="1080" height="1080" data-path="images/guides/best-practices/diataxis.webp" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/mintlify/mgh6fYMQy9DM5E4a/images/guides/best-practices/diataxis.webp?w=280&fit=max&auto=format&n=mgh6fYMQy9DM5E4a&q=85&s=26ac47cbd6491b139648ca243b7d88c6 280w, https://mintcdn.com/mintlify/mgh6fYMQy9DM5E4a/images/guides/best-practices/diataxis.webp?w=560&fit=max&auto=format&n=mgh6fYMQy9DM5E4a&q=85&s=59153e5613d8fc49ec2cb1d33e048878 560w, https://mintcdn.com/mintlify/mgh6fYMQy9DM5E4a/images/guides/best-practices/diataxis.webp?w=840&fit=max&auto=format&n=mgh6fYMQy9DM5E4a&q=85&s=27a983a4d2e3c22b65085d33a80757b2 840w, https://mintcdn.com/mintlify/mgh6fYMQy9DM5E4a/images/guides/best-practices/diataxis.webp?w=1100&fit=max&auto=format&n=mgh6fYMQy9DM5E4a&q=85&s=59eb28f9641db4fa809f2539e5e8fe28 1100w, https://mintcdn.com/mintlify/mgh6fYMQy9DM5E4a/images/guides/best-practices/diataxis.webp?w=1650&fit=max&auto=format&n=mgh6fYMQy9DM5E4a&q=85&s=7dca9a715257b92629769f5ac1874fd0 1650w, https://mintcdn.com/mintlify/mgh6fYMQy9DM5E4a/images/guides/best-practices/diataxis.webp?w=2500&fit=max&auto=format&n=mgh6fYMQy9DM5E4a&q=85&s=65bfc24435e42320d1d83aa97f55c391 2500w" />
</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>