Content types

Choose the right content type for your documentation goals.

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

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 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.

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 for success

1. Maintain purpose: Before writing, assign each page a specific content type and stay focused on that purpose throughout.
2. Optimize for freshness: Write evergreen documentation that remains accurate over time. Content tied to specific dates or frequently changing features belongs in changelogs or blog posts.
3. Think like your users: Consider different user personas when organizing content. See Understand your audience for more information.
4. Use templates: Start with 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

Content templates

Copy and modify templates for each content type.

Style and tone

Write effective documentation with consistent style.

Understand your audience

Research and define your documentation audience.

Navigation

Organize your documentation structure effectively.

Improve your docs

Use data and metrics to improve documentation.