> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Write technical documentation following the Diataxis framework by Daniele Procida. Use when writing, reviewing, or restructuring documentation to ensure correct separation of tutorials, how-to guides, reference, and explanation.

# SKILL

# Diataxis Documentation Framework

Complete reference for the Diataxis framework — a systematic approach to technical documentation authoring by Daniele Procida. All content sourced verbatim from [diataxis.fr](https://diataxis.fr/).

## When to Use This Skill

This skill should be triggered when:

* **Writing documentation**: Creating new docs pages of any type
* **Reviewing documentation**: Checking if content is in the right place and follows the right form
* **Restructuring documentation**: Reorganizing existing docs into proper Diataxis categories
* **Deciding content type**: Determining whether something should be a tutorial, how-to, reference, or explanation
* **Resolving confusion**: Distinguishing tutorials from how-to guides, or reference from explanation

## The Diataxis Compass

Use this decision table when you need to classify content:

| If the content...     | ...and serves the user's... | ...then it belongs in... |
| --------------------- | --------------------------- | ------------------------ |
| informs **action**    | **acquisition** of skill    | a **tutorial**           |
| informs **action**    | **application** of skill    | a **how-to guide**       |
| informs **cognition** | **application** of skill    | **reference**            |
| informs **cognition** | **acquisition** of skill    | **explanation**          |

Two questions to ask:

1. **Action or cognition?** Is this about *doing* something or *knowing* something?
2. **Acquisition or application?** Is the user *learning* or *working*?

Full compass guidance: `references/compass.md`

## The Four Documentation Types

### Tutorials (learning-oriented)

* An **experience** guided by a tutor, where the learner acquires skills by doing
* Teacher holds nearly all responsibility — learner just follows directions
* Concrete steps, no choices, no branching, ruthlessly minimal explanation
* Language: "We will...", "First, do X. Now, do Y.", "Notice that...", "You have built..."

**Full reference**: `references/tutorials.md`

### How-to Guides (goal-oriented)

* **Directions** that guide a competent user through a real-world problem
* Assumes the user already knows the basics and has a specific goal
* Can branch ("If this, do that"), addresses real-world conditions
* Language: "If you want X, do Y." Conditional imperatives.

**Full reference**: `references/how-to-guides.md`

### Reference (information-oriented)

* **Technical description** of the machinery — austere, factual, structured like the code
* Consulted while working, not read cover-to-cover
* Neutral, objective. Describe and only describe. No teaching, no opinions.
* Language: "X does Y.", "You must use X.", lists, tables, warnings.

**Full reference**: `references/reference.md`

### Explanation (understanding-oriented)

* **Discursive treatment** that permits reflection and deepens understanding
* Read after stepping away from work. Discusses why, provides context, weighs alternatives.
* Admits opinion and perspective. Makes connections across topics.
* Language: "The reason for X is...", "Consider...", analogies, history, alternatives.

**Full reference**: `references/explanation.md`

## Critical Distinctions

The most common mistake in documentation is mixing types. Read these when boundaries are unclear:

* **Tutorials vs How-to Guides**: `references/tutorials-how-to.md` — The single most common conflation in software documentation. Tutorials are safe, contrived, teacher-led. How-to guides are real-world, user-led, assume competence.
* **Reference vs Explanation**: `references/reference-explanation.md` — Key test: would you consult this *while working* (reference) or *after stepping away* (explanation)?

## Reference Files

All files in `references/` contain the complete, unabridged content from diataxis.fr:

### Getting Started

* **`references/index.md`** — Overview and introduction to Diataxis
* **`references/start-here.md`** — Getting started primer
* **`references/application.md`** — Applying Diataxis in practice

### The Four Types (read before writing any documentation)

* **`references/tutorials.md`** (16K) — Complete tutorial guidance with all principles
* **`references/how-to-guides.md`** (11K) — Complete how-to guide guidance
* **`references/reference.md`** (6K) — Complete reference documentation guidance
* **`references/explanation.md`** (7K) — Complete explanation guidance

### Practical Tools

* **`references/compass.md`** — The decision compass for classifying content
* **`references/how-to-use-diataxis.md`** — Workflow guidance for applying the framework

### Theory & Principles

* **`references/theory.md`** — Theoretical foundations overview
* **`references/foundations.md`** — Foundational concepts underpinning Diataxis
* **`references/map.md`** — The Diataxis map and its relationships
* **`references/quality.md`** (11K) — Theory of functional vs deep quality in documentation

### Boundaries & Edge Cases

* **`references/tutorials-how-to.md`** (14K) — Tutorials vs how-to guides (the most important distinction)
* **`references/reference-explanation.md`** — Reference vs explanation
* **`references/complex-hierarchies.md`** (8K) — Handling complex documentation structures

### Meta

* **`references/colophon.md`** — About Diataxis itself

## Working with This Skill

### Before Writing a Page

1. Determine which Diataxis type it is using the compass above
2. Read the full reference file for that type (e.g., `references/tutorials.md`)
3. Follow the language patterns and structural rules for that type
4. **Never mix types on a single page**

### When Reviewing Documentation

1. For each page, use the compass to verify its type
2. Flag any content that mixes types (e.g., explanation inside a how-to guide)
3. Check `references/tutorials-how-to.md` if tutorials and how-tos seem conflated
4. Check `references/reference-explanation.md` if reference and explanation seem blurred

### When Restructuring

1. Read `references/how-to-use-diataxis.md` for the overall workflow
2. Read `references/complex-hierarchies.md` for handling large documentation sites
3. Classify every existing page using the compass
4. Move misplaced content to its correct type

## Notes

* All reference content is Daniele Procida's original writing from diataxis.fr — do not paraphrase when the original words apply
* The reference files are the authority. When in doubt, re-read the relevant file.
* Source: [https://diataxis.fr/](https://diataxis.fr/) — Copyright Daniele Procida