keithpatton/diataxis

Diátaxis Documentation Governance

This skill enforces the Diátaxis framework for documentation. Diátaxis identifies four distinct documentation types based on user needs: tutorials, how-to guides, reference, and explanation. Each serves a different purpose and must be written differently.

Operating Modes

This skill operates in one of the following modes:

• classify: Identify which quadrant content belongs to
• audit: Analyze a doc set for gaps, imbalances, and violations
• generate: Create new documentation in a specified quadrant
• restructure: Split or reorganize existing mixed-mode content

The mode must be inferred from the user request or explicitly stated. If the operating mode cannot be confidently inferred, ask for clarification before proceeding.

Refusal with explanation is a valid and successful outcome when quadrant purity cannot be maintained.

Generate Mode Policy

For generate mode, one of the following must be true before producing content:

• The user explicitly states the target quadrant ("write a How-to for X"), OR
• The agent classifies the request, presents reasoning with confidence+evidence, and receives user confirmation

The Diátaxis Compass

Use this decision tree to classify content into exactly ONE quadrant:

| If content... | ...and serves user's... | ...then it belongs to... | |-------------------|---------------------------|--------------------------| | informs action | acquisition (study) | Tutorial | | informs action | application (work) | How-to Guide | | informs cognition | application (work) | Reference | | informs cognition | acquisition (study) | Explanation |

Two questions to ask:

1. Does this inform action (doing) or cognition (knowing)?
2. Does this serve acquisition (learning/study) or application (working)?

Quadrant Summary

Tutorial (learning-oriented)

A lesson that takes the learner through a practical experience. The instructor is responsible for the learner's success. Focus on doing, not explaining. Deliver results early and often. Minimize explanation. No choices or alternatives.

• Form: Sequential lesson with concrete steps
• Language: "We will...", "First, do X", "You'll notice that..."
• Not: Teaching concepts, offering alternatives, explaining why

How-to Guide (goal-oriented)

Directions that guide an already-competent user through a real-world problem. Assumes the reader knows what they want to achieve. Focused on work, not study.

• Form: Series of steps addressing a specific goal
• Language: "To achieve X, do Y", "If you want...", conditional imperatives
• Not: Teaching beginners, explaining concepts, describing machinery

Reference (information-oriented)

Technical description of the machinery. Austere, neutral, accurate. Structure mirrors the thing being described. The user consults it, not reads it.

• Form: Structured descriptions, tables, specifications
• Language: "X is...", "The options are...", factual statements
• Not: Instructing, explaining why, narrative, opinions

Explanation (understanding-oriented)

Discursive treatment that provides context, background, and answers "why". Makes connections, admits opinion, circles around the subject.

• Form: Prose discussion of a topic
• Language: "The reason for X is...", "This is because...", "Consider..."
• Not: Step-by-step procedures, technical specifications, teaching tasks

Core Workflow

For Classification

1. Read the content carefully
2. Apply the compass: action/cognition × acquisition/application
3. Identify the single quadrant
4. Report with confidence and evidence

For Generation

1. Confirm the target quadrant (stated or inferred with confirmation)
2. Apply quadrant constraints strictly
3. Refuse to blend quadrants; recommend splitting if needed
4. Validate output against quadrant characteristics

For Audit

1. Inventory all documentation
2. Classify each document
3. Identify gaps (missing quadrants)
4. Flag violations (mixed-mode, wrong quadrant)
5. Report imbalances (e.g., "reference-heavy, tutorial-poor")

For Restructure

1. Classify the existing content
2. Identify quadrant violations
3. Propose splits (one document per quadrant)
4. Present plan for user confirmation before changes

Output Requirements

When classifying or flagging violations, always provide:

• Quadrant: The identified type (Tutorial, How-to, Reference, Explanation)
• Confidence: high | medium | low
• Evidence: Specific phrases, structural patterns, or signals

Example:

Classified as How-to (high confidence). Evidence: imperative verbs ("configure", "set up"), goal-oriented heading, absence of conceptual framing, assumes reader competence.

Violation Detection

Flag these anti-patterns:

• Tutorial with explanation: Lengthy "why" sections, conceptual digressions
• How-to that teaches: Beginner framing, "let's learn" language
• Reference with narrative: First-person voice, procedural instructions
• Explanation with procedures: Numbered steps, imperative commands
• Mixed-mode documents: Multiple quadrant signals in single document

For detailed detection patterns and remediation, see references/anti-patterns.md.

Non-Goals

This skill does not:

• Invent documentation strategy or information architecture
• Decide product architecture or feature scope
• Merge multiple Diátaxis quadrants into a single document
• Override repository-specific documentation rules or style guides
• Generate content without explicit quadrant classification

Additional Resources

• Detailed quadrant characteristics: references/quadrants.md
• Classification decision tree: references/compass.md
• Anti-patterns and fixes: references/anti-patterns.md

Attribution

Diátaxis is the work of Daniele Procida. This skill encodes the Diátaxis framework for use by AI agents. For the authoritative source and complete documentation, see diataxis.fr.

Licensed under CC-BY-SA 4.0. Citation metadata available at the Diátaxis GitHub repository.