Documentation Taxonomy — Organizing Content for Developers

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

Documentation taxonomy is the practice of categorizing and organizing technical content into a logical structure. A well-designed taxonomy helps readers navigate, writers create consistent content, and search engines index pages correctly.

In this lesson, you will learn the major documentation taxonomy frameworks, how to organize content in your Repository, and how to apply these principles to real projects like the DodaTech documentation set.

What You'll Learn

You will understand the Diataxis and metadata-based taxonomy models, organize documentation using folder structures, and implement taxonomy in a static site generator.

Why It Matters

A good taxonomy reduces the time readers spend searching for information. It also helps writers know exactly where to place new content, preventing duplication and inconsistency.

Real-World Use

DodaTech uses a folder-based taxonomy where each section maps to a documentation type. Tutorials live under a tutorials folder, reference under reference. This structure makes it obvious where to add new content and how to find existing content.

flowchart TD
  A[Docs Repository] --> B[tutorials/]
  A --> C[how-to/]
  A --> D[reference/]
  A --> E[explanation/]
  B --> F[getting-started.md]
  B --> G[build-app.md]
  C --> H[reset-password.md]
  C --> I[configure-api.md]
  D --> J[api-endpoints.md]
  D --> K[cli-commands.md]
  E --> L[architecture.md]
  E --> M[security-model.md]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Taxonomy Frameworks

The Diataxis framework is the most popular taxonomy model. It uses two axes: learning versus doing and theory versus practice. This creates four quadrants.

An alternative is the metadata-based approach where pages are tagged with type, audience, and skill level. This allows flexible filtering but requires more upfront planning.

A third approach is the audience-based taxonomy. Content is organized by who reads it: end users, developers, system administrators, or project managers.

# Taxonomy configuration for a documentation build system
# This pattern organizes content into the four Diataxis quadrants
# and generates navigation automatically.

TAXONOMY_CONFIG = {
    "tutorials": {
        "folder": "tutorials",
        "icon": "book-open",
        "audience": "beginners",
        "navigation_weight": 10,
    },
    "how-to": {
        "folder": "how-to",
        "icon": "wrench",
        "audience": "intermediate",
        "navigation_weight": 20,
    },
    "reference": {
        "folder": "reference",
        "icon": "code",
        "audience": "all",
        "navigation_weight": 30,
    },
    "explanation": {
        "folder": "explanation",
        "icon": "book",
        "audience": "advanced",
        "navigation_weight": 40,
    },
}

def get_taxonomy_section(content_type: str) -> dict:
    """Return taxonomy config for a given content type."""
    section = TAXONOMY_CONFIG.get(content_type)
    if section:
        return section
    raise ValueError(f"Unknown content type: {content_type}")

Folder Structure Best Practices

Organize documentation by type first, then by feature. This keeps related content together and makes navigation predictable.

Use consistent naming: lowercase with hyphens for folders and filenames. Each folder should have an index page that explains what the section contains.

Include a README in the docs root that explains the taxonomy and where to place new content. New writers should be able to add a page without asking.

docs/
  tutorials/
    _index.md
    getting-started.md
    build-your-first-app.md
  how-to/
    _index.md
    configure-authentication.md
    deploy-to-production.md
  reference/
    _index.md
    api-endpoints.md
    configuration-options.md
  explanation/
    _index.md
    architecture-overview.md
    security-model.md
  _index.md

Common Mistakes

1. Organizing by Date Instead of Type

Blog-style organization by date buries important content. Organize by type or topic, not by when it was written.

2. Deep Nesting

More than three levels of nesting buries content and confuses navigation. Keep the hierarchy flat.

3. No Index Pages

Each section needs an index page that explains what the section contains and how to use it.

4. Mixing Languages or Formats

Keep all documentation in the same format. Mixing Markdown with reStructuredText or AsciiDoc creates inconsistency.

5. Ignoring Search

Taxonomy must work with search. Use tags and categories that align with what users actually search for.

6. No Cross-Reference Strategy

Pages should link to related content in other sections. A tutorial should link to the relevant reference page.

7. Taxonomy Without Enforcement

Without automated checks, writers will place content in wrong sections. Use CI checks that verify taxonomy based on folder paths.

Practice Questions

1. What are the four quadrants of the Diataxis framework?

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

2. Why is folder-based taxonomy better than tag-based taxonomy?

Folders enforce a single canonical location for each piece of content. Tags allow multiple overlapping categories but can lead to content living in unexpected places.

3. How deep should documentation folder nesting be?

Maximum three levels: section, subsection, page. Deeper nesting buries content and harms navigation.

4. What should each section's index page contain?

An overview of what the section covers, who it is for, and links to the most important pages in the section.

5. Challenge: Design a taxonomy for a documentation set with 50-plus pages. Write the folder structure, taxonomy config, and a README explaining where contributors should add new content.

FAQ

Mini Project

Take a documentation set you use regularly such as a popular framework or library. Map its folder structure and identify which taxonomy framework it follows. Write a one-page proposal for improving the taxonomy with before and after folder structure diagrams.

What's Next

Next: Writing Tutorials