This page explains different content types, when to use each one, and how to approach writing for each type.
Categorize using the Diátaxis framework
The Diátaxis framework is a helpful guide for categorizing content based on your audience’s needs. Documentation can generally be mapped into one of these types:- Tutorials: Learning-oriented content for new users
- How-to guides: Task-oriented guidance for specific problems
- Explanations: Understanding-oriented conceptual discussions
- Reference: Information-oriented technical descriptions
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
- Maintain purpose: Before writing, assign each page a specific content type and make it top of mind in the doc throughout your writing.
- 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.
- Think like your users: Consider different user personas when organizing content. See Understand your audience for more information.