Maintain Documentation with the Diataxis Method

You are helping the user organize and maintain their project documentation following the Diataxis framework.

What is Diataxis?

Diataxis (from Ancient Greek: dia — "across", taxis — "arrangement") is a systematic approach to technical documentation that organizes content into four categories based on user needs. See diataxis.fr for the full framework.

The Compass — Two Axes for Classification

Use two questions to classify any content (see references/compass.md):

1. "Is this about action or cognition?" — Does the reader do something or understand something?
2. "Is this about acquisition or application?" — Is the reader studying or working?

Key Distinctions

• Tutorials vs How-to guides: Tutorials teach ("follow me") for learners; how-to guides direct ("do this") for practitioners. Tutorials are complete end-to-end; how-to guides start and end at reasonable points the reader joins to their own work.
• Explanation vs Reference: Explanation discusses why (discursive, admits opinion); reference states what (austere, authoritative, no ambiguity).
• Action vs Cognition: Tutorials and how-to guides are practical (doing). Explanation and reference are theoretical (knowing).
• Acquisition vs Application: Tutorials and explanation serve learning/studying. How-to guides and reference serve working/coding.

Step 1: Discover Existing Documentation

1. Scan the project for documentation files:
   • Look for docs/, doc/, documentation/ directories
   • Check for markdown files at the project root: README.md, CONTRIBUTING.md, CHANGELOG.md
   • Look for other documentation formats: .rst, .adoc, .txt
   • Check for documentation configuration: mkdocs.yml, docusaurus.config.js, conf.py, antora.yml, hugo.toml
2. Read existing documentation to understand what is already covered.
3. If no documentation exists:
   • Inform the user: "No documentation found. Let's create a documentation structure from scratch."
   • Skip to Step 3: Propose Documentation Structure

Step 2: Classify Existing Documentation

Analyze each documentation page and classify it into one of the four Diataxis categories.

Respect Prior Classification Decisions

Before suggesting reclassification, check git history for deliberate prior moves:

git log --all --oneline --diff-filter=R -- 'docs/**/*.md'

If a file was intentionally moved between categories (e.g., a commit message like docs(diataxis): reclassify X as reference), respect that decision unless the user explicitly asks to revisit it. A prior deliberate reclassification reflects a judgment that the compass alone may not capture — flag it to the user rather than overriding it.

Classification Rules

Use the compass questions and these signals. For detailed writing guidance per category, see the reference files in references/.

A page is a Tutorial if it (see references/tutorials.md):

• Guides a beginner through a complete learning experience under the author's direction
• Has a clear starting point and end goal, delivering visible results at each step
• Uses first-person plural: "In this tutorial, we will...", "First, do x. Now, do y."
• Follows a sequential narrative where the reader learns by doing
• Focuses on learning acquisition, not on accomplishing a real-world task
• Minimises explanation — links out instead of digressing

A page is a How-to guide if it (see references/how-to-guides.md):

• Addresses a specific, concrete goal from the user's perspective (not the tool's)
• Assumes the reader already has basic knowledge and knows what they want
• Uses precise titles: "How to integrate monitoring", not "Monitoring"
• Provides an executable solution: "if facing this situation, follow these steps"
• Starts and ends at reasonable points — reader joins it to their own work
• Stays practical without teaching concepts or including reference tables

A page is Explanation if it (see references/explanation.md):

• Discusses concepts, background, design decisions, or trade-offs
• Answers "Can you tell me about...?" — titles work with an implicit "About" prefix
• Makes connections between concepts and provides context (history, reasons, alternatives)
• Uses discursive prose that admits opinion and weighs multiple perspectives
• Could make sense to read away from the keyboard
• Resists absorbing instruction or reference material

A page is Reference if it (see references/reference.md):

• Describes APIs, configurations, CLI flags, or data structures authoritatively
• Is structured for lookup (consulted, not read end-to-end)
• Is austere, factual, and precise — states facts using declarative language
• Mirrors the structure of the machinery it describes
• Uses consistent, standard patterns across all entries
• Provides minimal examples that demonstrate usage without teaching

Mixed Content

Many pages contain content from multiple categories. Flag these for the user and suggest how to split them:

• "This page mixes tutorial content (the getting started section) with reference content (the API table). Consider splitting into a tutorial and a reference page."

Boundary Cases

Some content types sit at the compass boundary. Do not apply the compass mechanically — consider the page's structure and intended use:

• Troubleshooting: A lookup table of symptoms, causes, and fixes is Reference (structured for consultation, mirrors problem structure, austere facts). A page that walks through a diagnostic process step-by-step is How-to (goal-oriented sequence). The format determines the category, not the subject matter.
• FAQ pages: Individual Q&A entries are often Reference (lookup). A curated FAQ that builds understanding is Explanation.
• Migration guides: Step-by-step upgrade instructions are How-to. A discussion of what changed and why is Explanation.

When in doubt about a boundary case, consider: how will the reader use this page? Consulted for lookup → Reference. Followed as steps → How-to.

Present Classification Results

Present results as a table:

| File                     | Current Category | Suggested Category | Notes              |
|--------------------------|------------------|--------------------|--------------------------------|
| docs/getting-started.md  | -                | Tutorial           | Good tutorial structure         |
| docs/api.md              | -                | Reference          | Contains some how-to content   |
| docs/architecture.md     | -                | Explanation        | Well-structured explanation     |

Step 3: Propose Documentation Structure

Based on the analysis, propose a Diataxis-aligned directory structure.

Standard Directory Layout

docs/
  tutorials/           # Learning-oriented
    getting-started.md
    first-project.md
  how-to/              # Task-oriented
    install.md
    configure.md
    deploy.md
  explanation/         # Understanding-oriented
    architecture.md
    design-decisions.md
  reference/           # Information-oriented
    api.md
    configuration.md
    cli.md

Adaptation Rules

• Adapt to existing tooling: If the project uses mkdocs, docusaurus, antora, hugo, or similar, propose a structure compatible with that tool's conventions.
• Adapt to existing structure: If the project already has a docs structure that partially aligns with Diataxis, propose minimal changes to align it fully rather than a complete restructure.
• Keep what works: Do not propose moving content that is already well-categorized.
• Respect the project conventions: If the project uses a specific naming convention (kebab-case, snake_case, etc.), follow it.

Identify Documentation Gaps

After classifying existing content, identify missing pieces:

• No tutorials? Suggest creating a getting-started tutorial.
• No how-to guides? Suggest guides for the most common tasks (installation, configuration, deployment).
• No explanation? Suggest architecture or design decision documents.
• No reference? Suggest API, configuration, or CLI reference pages.

Present gaps clearly:

Documentation gaps identified:
- [ ] Missing: Tutorial for getting started
- [ ] Missing: How-to guide for deployment
- [ ] Missing: Reference for configuration options
- [x] Covered: Architecture explanation exists

Step 4: Execute Changes

Always ask the user before making changes. Present the plan and wait for approval.

When Restructuring

1. Present the proposed file moves and renames
2. Wait for user approval
3. Move files to their new locations
4. Update any internal links between documentation pages
5. Update navigation configuration (mkdocs.yml, sidebar config, etc.) if applicable
6. Verify no broken links remain

When Creating New Pages

1. Present which pages you suggest creating
2. Wait for user approval
3. Create pages with proper structure for their category, using the matching template in references/templates.md (tutorial, how-to guide, explanation or reference)
4. Fill in content based on project analysis (source code, existing docs, configuration files)

When Improving Existing Pages

If a page is already in the right category but needs improvement to better follow Diataxis principles:

1. Identify specific issues (mixed content, wrong tone, missing structure)
2. Present suggested changes to the user
3. Apply changes after approval

Important Guidelines

• Do not force the framework: If the project is small and a single README covers everything well, say so. Diataxis is most valuable for projects with substantial documentation needs.
• Be pragmatic: A partially-organized documentation set is better than no documentation. Suggest incremental improvements rather than demanding perfection.
• Preserve content: When restructuring, never delete content. Move and reorganize, but keep all existing information.
• Maintain links: When moving files, update all cross-references and navigation configurations.
• Respect the user's decisions: If the user disagrees with a classification or restructuring suggestion, accept their decision and adjust accordingly.
• Quality awareness: Diataxis facilitates quality but cannot guarantee it — accuracy, completeness, and good writing remain the author's responsibility. See references/quality.md for quality dimensions.
• Use the compass when in doubt: When classification is unclear or writing feels difficult, apply the two compass questions. See references/compass.md.

Reference Documents

Detailed writing guidance for each category, extracted from diataxis.fr:

• references/tutorials.md — Pedagogical principles, language conventions, anti-patterns
• references/how-to-guides.md — Writing principles, scope, distinction from tutorials
• references/explanation.md — Characteristics, discussion areas, naming test
• references/reference.md — Austerity principles, structure mirroring, examples
• references/compass.md — Two-axis decision tool for classification
• references/quality.md — Functional and deep quality dimensions