Content Types Matrix: Choosing the Right Format

In this tutorial, you will learn about Content Types Matrix: Choosing the Right Format. We cover key concepts, practical examples, and best practices to help you master this topic.

A content types matrix maps user needs to documentation formats — tutorials, how-to guides, reference docs, explanations, and troubleshooting guides.

What You'll Learn

You will learn the Diataxis framework of documentation types, how to choose the right format for each user need, and how to design content type templates.

Why It Matters

Using the wrong format frustrates users. A reference page does not teach concepts well, and a tutorial is inefficient for looking up details. The right format speeds up user success.

Real-World Use

DodaTech uses the Diataxis model: tutorials teach beginners, how-to guides solve specific problems, reference docs provide technical details, and explanations build understanding.

flowchart LR
  A[User Need] --> B{What is the goal?}
  B --> C[Learn] --> D[Tutorial]
  B --> E[Solve] --> F[How-To Guide]
  B --> G[Look Up] --> H[Reference]
  B --> I[Understand] --> J[Explanation]
  C:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

The Diataxis Framework

1. Tutorials

Tutorials are lessons that guide a beginner through completing a task step by step. They focus on doing, not knowing.

## Tutorial: Create Your First Python Variable

**Goal**: Assign a value to a variable and print it.
**Time**: 5 minutes
**Prerequisites**: Python installed

Step 1: Open your terminal and run `python3`
Step 2: Type `message = "Hello, World!"`
Step 3: Type `print(message)`
Step 4: Observe the output

2. How-To Guides

How-to guides solve specific problems. They assume the reader already understands the basics.

def convert_csv_to_json(csv_path, json_path):
    import csv, json
    data = []
    with open(csv_path) as f:
        reader = csv.DictReader(f)
        for row in reader:
            data.append(row)
    with open(json_path, 'w') as f:
        json.dump(data, f, indent=2)

convert_csv_to_json('input.csv', 'output.json')
print("Conversion complete")

3. Reference Documentation

Reference docs describe the system. They are accurate, complete, and boring — exactly what users need to look up details.

# API Reference: /users endpoint
GET /users
  Description: List all users
  Parameters:
    - page (int, optional): Page number
    - limit (int, optional): Results per page
  Response: 200 OK
    - users (array): List of user objects
    - total (int): Total count

4. Explanations

Explanations provide background and context. They help users build mental models.

## Why Python Uses Indentation

Python uses indentation to define code blocks instead of curly braces
like C or `begin`/`end` like Pascal. This choice forces consistent
formatting, making Python code more readable than most languages.

**Before Python**:
if (condition) {
    doSomething();
}

**Python**:
if condition:
    do_something()

Content Types Matrix

Common Mistakes

1. Writing Tutorials as Reference

A tutorial that lists every option and parameter is not a tutorial. Tutorials should focus on one path through the system, not all possibilities.

2. Writing Reference as Tutorial

A reference page that uses narrative prose buries the information users need to look up. Use consistent formatting for reference content.

3. Mixing Types in One Page

A single page that tries to be tutorial, reference, and explanation confuses readers. Split into separate pages.

4. No Clear Entry Point

Users do not know which content type to start with. Provide guidance: "New here? Start with the tutorial. Need a specific answer? Check the reference."

5. Ignoring the Troubleshooting Type

Troubleshooting content is highly valued by users but often neglected. Create dedicated troubleshooting pages for common errors.

Practice Questions

1. What are the four Diataxis content types?

Tutorials, how-to guides, reference documentation, and explanations.

2. Which content type would you use for a user who needs to look up an API parameter?

Reference documentation. It is designed for quick lookup of specific details.

3. What is the main difference between a tutorial and a how-to guide?

A tutorial teaches a beginner step by step. A how-to guide solves a specific problem and assumes the reader has basic knowledge.

4. Why should content types not be mixed on a single page?

Each type has a different purpose and structure. Mixing them confuses users who have a specific goal.

5. Challenge: Take a documentation page and identify which Diataxis type it uses. Then rewrite a section as a different type.

FAQ

Mini Project

Take a documentation section and create four versions of the same topic using each Diataxis type: a tutorial, how-to guide, reference page, and explanation. Note the structural differences.

What's Next

Now that you understand content types, learn Information Architecture for organizing them. Then study SEO Content Strategy to make them findable.