Content Types

Documentation needs to be organized around the specific goal you’re trying to help the user achieve.

​

Categorize using the Diataxis framework

The Diataxis 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

​

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 throughout, e.g. “you will notice that” or “If this doesn’t show, you probably forgot to”
  • 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, but avoid “duh” statements (e.g. press enter to submit)
  • Minimize context beyond what’s 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 (e.g. tables, naming, API specs).
  • Avoid explanatory content. Focus on examples that are easy to copy and modify.

Reference documentation should be super scannable. As a developer, you want to find ‘how do I do this specific task.’ When I get there, I want to be able to clearly understand the parameters.

- Sarah Edwards, Documentation Engineer at Datastax

​

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

For complex or multi-threaded releases that touch many parts of your product, you need to provide both practical guidance and conceptual understanding in your documentation. Users need to grasp when and why to use something, not just how.

- CT Smith, Head of Docs at Payabli

​

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. As Ethan from GitHub says, “If something represents a moment in time of what a feature looks like on a specific date, it’s probably better suited for a blog post than in the docs.” Or if something changes very frequently, such as pricing information, avoid putting it in your docs.
3. Think Like Your Users: Consider different user personas when organizing content. Check out Know Your Audience for more information.

While the Diataxis 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.

The trap is to think one framework can rule them all. Don’t be so inflexible in enforcing content types that you forget the reader.

- CT Smith, Head of Docs at Payabli