Introduction to Documentation Types — Why Taxonomy Matters

In this tutorial, you will learn about Introduction to Documentation Types. We cover key concepts, practical examples, and best practices to help you master this topic.

Documentation types define the categories of content you create for users. Each type serves a specific audience, purpose, and reading context. Understanding this taxonomy is the foundation of professional technical writing.

In this lesson, you will learn what documentation types are, why the taxonomy matters, and how the Diataxis framework categorizes technical content. This knowledge applies whether you write for DodaZIP, Doda Browser, or any software product.

What You'll Learn

You will understand the four-quadrant Diataxis model, identify documentation types by their audience and goal, and apply taxonomy thinking to structure a real documentation set.

Why It Matters

Without a clear taxonomy, documentation becomes a disorganized pile of files. Readers cannot find what they need. Writers duplicate content. Support teams answer the same questions repeatedly.

Real-World Use

The Diataxis framework improved documentation usability at DodaTech by separating learning content from reference content, reducing support tickets for the DodaZIP compression library by 40 percent in three months.

flowchart LR
  A[Documentation] --> B{Tutorials}
  A --> C{How-To Guides}
  A --> D{Reference Docs}
  A --> E{Explanation}
  B --> F[Learning by Doing]
  C --> G[Solving Problems]
  D --> H[Looking Up Details]
  E --> I[Understanding Concepts]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Understanding the Diataxis Framework

The Diataxis model organizes documentation into four categories based on two axes: learning versus doing, and theory versus practice.

Tutorials are learning-oriented and practice-based. They guide a beginner through a complete task step by step. The goal is a working outcome, not deep understanding.

How-to guides are goal-oriented and practice-based. They solve a specific problem for a reader who already knows the basics. Each guide addresses one task.

Explanation or conceptual documentation is learning-oriented and theory-based. It describes how a system works, why it is designed that way, and what trade-offs exist.

Reference documentation is information-oriented and theory-based. It describes the system in precise detail: API endpoints, function signatures, configuration options.

Why Taxonomy Matters

Without taxonomy, writers fall into common traps. They write tutorials that read like reference docs. They include conceptual explanations in API specs. They confuse how-to guides with tutorials.

A clear taxonomy solves these problems by giving each content type a specific job. When a writer knows they are writing a how-to guide, they focus on the single task. When a writer knows they are writing a tutorial, they focus on step-by-step learning.

# Example: A documentation router that serves content by type
# This pattern is used in DodaTech's documentation build system
# to organize content into the correct taxonomy category.

DOCS_TAXONOMY = {
    "tutorials": {
        "audience": "beginners",
        "goal": "learning by doing",
        "structure": "step-by-step",
        "outcome": "working result",
    },
    "how-to-guides": {
        "audience": "intermediate users",
        "goal": "solving specific problems",
        "structure": "task-focused",
        "outcome": "completed task",
    },
    "reference": {
        "audience": "all users",
        "goal": "looking up details",
        "structure": "alphabetical or categorical",
        "outcome": "accurate information",
    },
    "explanation": {
        "audience": "users seeking understanding",
        "goal": "comprehending concepts",
        "structure": "narrative",
        "outcome": "deep understanding",
    },
}

def route_content(content_type: str) -> str:
    """Return the appropriate section for a content type."""
    if content_type in DOCS_TAXONOMY:
        return f"Content belongs in {content_type} section"
    return "Unknown documentation type; review taxonomy"

Common Mistakes

1. Ignoring Taxonomy Altogether

Writing without considering type produces inconsistent content that confuses readers about whether they are learning or looking up information.

2. Using the Same Structure for All Types

Every documentation type needs a different structure. A tutorial needs numbered steps. A reference needs categorized entries. Using one template for everything fails both audiences.

3. Writing Tutorials That Teach Nothing

A tutorial that just lists steps without explaining why each step matters leaves readers unable to adapt what they learned.

4. Making Reference Docs Too Narrative

Reference documentation with too much storytelling buries the specific details developers need to find quickly.

5. Mixing Multiple Types in One Page

A single page that tries to teach, reference, and explain simultaneously fails at all three goals. Keep types separate.

6. Forgetting the Audience

Each type targets a different audience. Tutorials target beginners. Reference targets experienced users. Writing a tutorial for experts or a reference for beginners misses both marks.

7. No Cross-References Between Types

Types should link to each other. A tutorial should link to relevant reference pages. A how-to guide should link to conceptual explanations. Without cross-references, readers hit dead ends.

Practice Questions

1. What are the four documentation types in the Diataxis framework?

Tutorials, how-to guides, reference documentation, and explanation or conceptual guides.

2. What is the primary goal of a tutorial?

To guide a beginner through a complete task resulting in a working outcome. The focus is learning by doing.

3. How does a how-to guide differ from a tutorial?

A how-to guide solves a specific problem for someone who already knows the basics. A tutorial assumes no prior knowledge.

4. Why is taxonomy important for documentation sets?

It prevents mixing content types, ensures consistent structure, and helps readers find the right information at the right time.

5. Challenge: Take a piece of documentation you use regularly and categorize it using the Diataxis framework. If it mixes types, rewrite it as two separate pages following the correct structure.

FAQ

Mini Project

Create a documentation taxonomy map for a project you know well. List every piece of documentation the project has. Categorize each into tutorials, how-to guides, reference, or explanation. Identify gaps where a type is missing and write a one-paragraph proposal for filling each gap.

What's Next

Next: Documentation Taxonomy Deep Dive