Skip to content

Documentation Philosophy

This documentation follows the Diátaxis framework - a systematic approach to technical documentation that organizes content by user needs rather than topic.

Last updated convention: We add a "Last updated" footer on hub pages (index pages). For detailed change history, rely on git history.

Why Diátaxis?

Most documentation fails because it mixes different types of content together. A tutorial suddenly becomes a reference guide. An explanation drifts into how-to instructions. The result is documentation that's hard to navigate and hard to maintain.

Diátaxis solves this by recognizing that documentation serves four distinct purposes, each requiring different content and writing styles.

The Four Quadrants

Diátaxis documentation structure

The Diátaxis documentation system divides content into four types based on user needs.

Tutorials (Learning-Oriented)

Location: Get Started

Purpose: Take users by the hand through a series of steps to complete a project.

Characteristics:

  • Learning-oriented
  • Assumes no prior knowledge
  • Shows the user that they can do something
  • Gives the user a successful experience

Example: "Your First Content Audit" walks through a complete audit workflow step-by-step.

How-to Guides (Task-Oriented)

Location: How-to

Purpose: Help users accomplish a specific task.

Characteristics:

  • Goal-oriented
  • Assumes some knowledge
  • Shows the user how to do something
  • Solves a specific problem

Example: "Configure MCP Servers" explains how to set up BigQuery, DataForSEO, and Wrike connections.

Reference (Information-Oriented)

Location: Reference

Purpose: Provide technical descriptions of the system.

Characteristics:

  • Information-oriented
  • Describes the machinery
  • Accurate and complete
  • Organized for quick lookup

Example: "Command Reference" lists all commands with their parameters and outputs.

Explanation (Understanding-Oriented)

Location: Explanation

Purpose: Clarify and illuminate topics through discussion.

Characteristics:

  • Understanding-oriented
  • Provides context and background
  • Explains why things are the way they are
  • Can be read at leisure, away from the keyboard

Example: "Architecture" explains the layered plugin system and design decisions.

How Our Docs Map to Diátaxis

Section Diátaxis Type User Need
Get Started Tutorials "I want to learn"
Features Reference + Tutorials "What can this do?"
How-to How-to Guides "I need to accomplish X"
Reference Reference "I need to look up Y"
Explanation Explanation "I want to understand why"

The "Features" Addition

Our documentation extends Diátaxis with a Features section. This is a practical addition that serves as:

  • A product showcase for new users discovering capabilities
  • A bridge between tutorials and reference
  • A navigation aid for users who know what they want but not where to find it

Divio's own documentation uses this pattern with their Features section.

Writing Guidelines by Section

Get Started (Tutorials)

  • Write in second person ("you")
  • Be encouraging and positive
  • Include every step, even obvious ones
  • Don't explain - just show what to do
  • End with a working result

How-to (Guides)

  • Start with a clear goal statement
  • Assume the reader knows what they want
  • Be direct and practical
  • Don't teach - just solve the problem

Reference

  • Be complete and accurate
  • Use consistent formatting
  • Don't explain why - just describe what
  • Organize for lookup, not reading

Explanation

  • Take time to explore topics
  • Provide context and background
  • Discuss alternatives and trade-offs
  • Connect to the bigger picture

Further Reading

Contributing to Documentation

When adding new documentation:

  1. Identify the quadrant - What user need does this serve?
  2. Follow the conventions - Use the writing style for that quadrant
  3. Link appropriately - Cross-reference related content in other quadrants
  4. Don't mix types - Keep tutorials separate from reference, etc.

See Contributing for detailed guidelines.