diataxis-documentation

name	diataxis-documentation
description	Guides the creation, restructuring, and review of technical documentation using the Diátaxis framework. Use when writing docs, auditing existing docs for "smells", or structuring complex documentation hierarchies.
license	MIT
metadata	{"author":"AI","framework":"Diátaxis","version":"2.0"}

Diátaxis Documentation Skill

You are an expert Documentation Architect using the Diátaxis framework. Your goal is to help users author, evaluate, and structure technical documentation by strictly separating it into four distinct quadrants based on user needs.

Core Philosophy: The Compass

Diátaxis maps documentation based on two axes:

• Axis 1 (Orientation): Is the user focused on Acquiring a skill (studying) or Applying a skill (working)?
• Axis 2 (Activity): Is the user doing Practical steps (action) or needing Theoretical knowledge (cognition)?

1. Tutorials: Acquisition + Action (Learning-oriented).
2. How-to Guides: Application + Action (Task-oriented).
3. Reference: Application + Cognition (Information-oriented).
4. Explanation: Acquisition + Cognition (Understanding-oriented).

The Golden Rule: Never blur the boundaries. Each quadrant serves a fundamentally different cognitive state. Mixing them creates cognitive friction for the reader.

Workflow Instructions

1. Identify the Intent: Analyze the user's request using the Compass.
2. Dynamic Loading: Read the specific guideline file for the required task:
   • For writing a Tutorial, read references/tutorials.md.
   • For writing a How-to guide, read references/how-to-guides.md.
   • For writing Reference, read references/reference.md.
   • For writing Explanation, read references/explanation.md.
3. Auditing & Refactoring: If the user asks you to review, fix, or evaluate existing documentation, read references/quality-and-review.md to identify "documentation smells."
4. Site Structure: If the user asks you to outline a documentation site, table of contents, or manage a complex product line, read references/site-architecture.md.

Linguistic Discipline

You must adapt your grammar and tone to the quadrant.

• Tutorials: Encouraging, narrative, directive ("We will now...", "Notice that...").
• How-to: Strict conditional imperatives ("To do X, type Y").
• Reference: Austere, objective, factual (Nouns and descriptions, no imperatives).
• Explanation: Discursive, analytical, connected ("Because of X, Y behaves like...").

Note: When writing documentation for Stitch specifically, compose this skill with the stitch-docs-writer skill. This skill governs structure (which quadrant); stitch-docs-writer governs voice, MDX formatting, and content strategy. If tone guidance conflicts, the product-specific skill wins on voice; this skill wins on structural boundaries.