diataxis
Helps maintain documentation pages based on the Diataxis method. Analyzes existing
Install
npx skills add https://github.com/rlespinasse/agent-skills/tree/main/skills/diataxis
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rlespinasse-agent-skills@llmmart
git clone https://github.com/rlespinasse/agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rlespinasse/agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.
| Category | Orientation | Purpose | Form |
|---|---|---|---|
| Tutorials | Learning-oriented | Guide a beginner through learning | A lesson |
| How-to guides | Task-oriented | Help accomplish a specific goal | A series of steps |
| Explanation | Understanding-oriented | Deepen understanding through discussion | A discursive essay |
| Reference | Information-oriented | Provide precise technical descriptions | Dry, accurate facts |
The Compass — Two Axes for Classification
Use two questions to classify any content (see references/compass.md):
| Acquisition (study) | Application (work) | |
|---|---|---|
| Action (practical) | Tutorial | How-to guide |
| Cognition (theoretical) | Explanation | Reference |
- "Is this about action or cognition?" — Does the reader do something or understand something?
- "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
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
- Look for
Read existing documentation to understand what is already covered.
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
- Present the proposed file moves and renames
- Wait for user approval
- Move files to their new locations
- Update any internal links between documentation pages
- Update navigation configuration (mkdocs.yml, sidebar config, etc.) if applicable
- Verify no broken links remain
When Creating New Pages
- Present which pages you suggest creating
- Wait for user approval
- Create pages with proper structure for their category, using the matching template in references/templates.md (tutorial, how-to guide, explanation or reference)
- 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:
- Identify specific issues (mixed content, wrong tone, missing structure)
- Present suggested changes to the user
- 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
Files (agent-skills)
-
evals
-
evals.json 9.8 KB
Loading…
-
-
references
-
compass.md 1.9 KB
Loading… -
explanation.md 2.6 KB
Loading… -
how-to-guides.md 2.9 KB
Loading… -
quality.md 2.1 KB
Loading… -
reference.md 2.4 KB
Loading… -
templates.md 2.4 KB
Loading… -
tutorials.md 3.9 KB
Loading…
-
-
SKILL.md 12.8 KB
--- name: diataxis description: Helps maintain documentation pages based on the Diataxis method. Analyzes existing docs, classifies pages into tutorials/how-to/explanation/reference categories, identifies gaps, and helps create or restructure documentation following Diataxis principles. Use when user mentions documentation structure, Diataxis, doc categories, tutorials vs how-to guides, or reorganizing docs. For checking README claims against code, see verify-readme-features. --- # 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](https://diataxis.fr/) for the full framework. | Category | Orientation | Purpose | Form | | ----------------- | ---------------------- | ---------------------------------------- | ------------------- | | **Tutorials** | Learning-oriented | Guide a beginner through learning | A lesson | | **How-to guides** | Task-oriented | Help accomplish a specific goal | A series of steps | | **Explanation** | Understanding-oriented | Deepen understanding through discussion | A discursive essay | | **Reference** | Information-oriented | Provide precise technical descriptions | Dry, accurate facts | ### The Compass — Two Axes for Classification Use two questions to classify any content (see [references/compass.md](references/compass.md)): | | Acquisition (study) | Application (work) | | --- | --- | --- | | **Action** (practical) | Tutorial | How-to guide | | **Cognition** (theoretical) | Explanation | Reference | 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-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: ```bash 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](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](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](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](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: ```text | 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 ```text 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: ```text 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](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](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](references/compass.md). ## Reference Documents Detailed writing guidance for each category, extracted from [diataxis.fr](https://diataxis.fr/): - [references/tutorials.md](references/tutorials.md) — Pedagogical principles, language conventions, anti-patterns - [references/how-to-guides.md](references/how-to-guides.md) — Writing principles, scope, distinction from tutorials - [references/explanation.md](references/explanation.md) — Characteristics, discussion areas, naming test - [references/reference.md](references/reference.md) — Austerity principles, structure mirroring, examples - [references/compass.md](references/compass.md) — Two-axis decision tool for classification - [references/quality.md](references/quality.md) — Functional and deep quality dimensions
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.