diff --git a/skills/diataxis/SKILL.md b/skills/diataxis/SKILL.md new file mode 100644 index 0000000..e66b342 --- /dev/null +++ b/skills/diataxis/SKILL.md @@ -0,0 +1,126 @@ +--- +name: diataxis +description: > + Write, review, classify, and restructure documentation using the Diataxis framework. + Diataxis defines four documentation types — tutorials, how-to guides, reference, explanation — + based on two axes: action vs. cognition, and acquisition vs. application. + Use when writing docs, reviewing docs for quality, classifying existing content into the four types, + restructuring documentation, deciding what kind of doc to write, or when asked about + "Diataxis", "documentation types", "tutorial vs how-to", "reference vs explanation", + "documentation structure", "documentation quality", or "documentation framework". +--- + +# Diataxis Documentation Framework + +IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any documentation tasks. Always consult the reference files below rather than relying on general knowledge. + +## Source of Truth + +All reference files below are symlinked from the Diataxis repo and always reflect the latest content. Read them for authoritative guidance. + +## Compressed Index + +``` +references/ +├── Core +│ ├── start-here.rst — 5-min primer: the four types + two axes +│ ├── theory.rst — Full theoretical grounding +│ ├── foundations.rst — Why documentation needs structure +│ ├── map.rst — The two-dimensional map (action/cognition x acquisition/application) +│ └── compass.rst — Decision tool: classify content into the four types +├── The Four Types +│ ├── tutorials.rst — Principles for learning-oriented docs (lessons, guided practice) +│ ├── how-to-guides.rst — Principles for goal-oriented docs (step-by-step task completion) +│ ├── reference.rst — Principles for information-oriented docs (austere descriptions) +│ └── explanation.rst — Principles for understanding-oriented docs (context, why, discussion) +├── Key Distinctions +│ ├── tutorials-how-to.rst — Tutorial vs how-to: the most common confusion +│ └── reference-explanation.rst — Reference vs explanation: when to describe vs discuss +└── Applying Diataxis + ├── application.rst — Practical application guide + ├── how-to-use-diataxis.rst — Iterative workflow: assess → decide → act → repeat + ├── complex-hierarchies.rst — Handling large/complex doc structures + └── quality.rst — Functional quality vs deep quality +``` + +## The Four Types at a Glance + +``` + │ ACTION (practical) │ COGNITION (theoretical) +──────────────┼────────────────────────┼────────────────────────── + ACQUISITION │ TUTORIAL │ EXPLANATION + (study) │ "We will..." │ "The reason is..." + │ Learning experience │ Context, why, discussion +──────────────┼────────────────────────┼────────────────────────── + APPLICATION │ HOW-TO GUIDE │ REFERENCE + (work) │ "If you want x, do y" │ "X is / X does..." + │ Task completion │ Austere description +``` + +## Compass — Classify Any Content + +Ask two questions: +1. Does it inform **action** (do something) or **cognition** (understand something)? +2. Does it serve **acquisition** (learning/study) or **application** (working/doing)? + +Result: action+acquisition=tutorial | action+application=how-to | cognition+application=reference | cognition+acquisition=explanation + +For full decision logic, read `references/compass.rst`. + +## Quick Rules Per Type + +### Tutorials +- Provide a learning experience through doing, not teaching +- Show the goal upfront, deliver visible results early +- Use "We will..." language; minimize explanation (link to it) +- Must be perfectly reliable — learner must never get stuck +- Read `references/tutorials.rst` for full principles + +### How-to Guides +- Address real-world goals, not machinery operations +- Assume competence; focus purely on action +- Title = exactly what the guide shows how to do +- Handle edge cases; omit the unnecessary +- Read `references/how-to-guides.rst` for full principles + +### Reference +- Describe and only describe — neutral, austere, complete +- Mirror the structure of the thing being documented +- Adopt standard, consistent patterns throughout +- Provide examples for illustration, not explanation +- Read `references/reference.rst` for full principles + +### Explanation +- Make connections, provide context, explain why +- Admit opinion and perspective; consider alternatives +- Can discuss history, design decisions, trade-offs +- Keep closely bounded to the topic +- Read `references/explanation.rst` for full principles + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Tutorial explains too much | Move explanation to explanation docs, link to it | +| How-to teaches background | Strip to action steps only | +| Reference includes opinions | Move discussion to explanation | +| Explanation gives step-by-step | Move procedure to how-to guide | +| Mixing types in one doc | Split into separate docs by type | + +For the critical tutorial-vs-howto distinction, read `references/tutorials-how-to.rst`. +For reference-vs-explanation, read `references/reference-explanation.rst`. + +## Workflow for Applying Diataxis + +1. Pick any piece of documentation +2. Use the compass to classify it (action/cognition x acquisition/application) +3. Assess: does it serve the identified user need well? +4. Decide one single improvement action +5. Do it and ship it +6. Repeat + +Do not plan a grand restructuring. Work iteratively, one improvement at a time. Documentation is never finished but always complete. + +For full workflow guidance, read `references/how-to-use-diataxis.rst`. +For complex documentation structures, read `references/complex-hierarchies.rst`. +For quality theory (functional vs deep quality), read `references/quality.rst`. diff --git a/skills/diataxis/references/application.rst b/skills/diataxis/references/application.rst new file mode 120000 index 0000000..23d5278 --- /dev/null +++ b/skills/diataxis/references/application.rst @@ -0,0 +1 @@ +../../../application.rst \ No newline at end of file diff --git a/skills/diataxis/references/compass.rst b/skills/diataxis/references/compass.rst new file mode 120000 index 0000000..ab9ca38 --- /dev/null +++ b/skills/diataxis/references/compass.rst @@ -0,0 +1 @@ +../../../compass.rst \ No newline at end of file diff --git a/skills/diataxis/references/complex-hierarchies.rst b/skills/diataxis/references/complex-hierarchies.rst new file mode 120000 index 0000000..ec7cfd8 --- /dev/null +++ b/skills/diataxis/references/complex-hierarchies.rst @@ -0,0 +1 @@ +../../../complex-hierarchies.rst \ No newline at end of file diff --git a/skills/diataxis/references/explanation.rst b/skills/diataxis/references/explanation.rst new file mode 120000 index 0000000..4704e97 --- /dev/null +++ b/skills/diataxis/references/explanation.rst @@ -0,0 +1 @@ +../../../explanation.rst \ No newline at end of file diff --git a/skills/diataxis/references/foundations.rst b/skills/diataxis/references/foundations.rst new file mode 120000 index 0000000..ae45a3a --- /dev/null +++ b/skills/diataxis/references/foundations.rst @@ -0,0 +1 @@ +../../../foundations.rst \ No newline at end of file diff --git a/skills/diataxis/references/how-to-guides.rst b/skills/diataxis/references/how-to-guides.rst new file mode 120000 index 0000000..4f456e7 --- /dev/null +++ b/skills/diataxis/references/how-to-guides.rst @@ -0,0 +1 @@ +../../../how-to-guides.rst \ No newline at end of file diff --git a/skills/diataxis/references/how-to-use-diataxis.rst b/skills/diataxis/references/how-to-use-diataxis.rst new file mode 120000 index 0000000..61f78f9 --- /dev/null +++ b/skills/diataxis/references/how-to-use-diataxis.rst @@ -0,0 +1 @@ +../../../how-to-use-diataxis.rst \ No newline at end of file diff --git a/skills/diataxis/references/map.rst b/skills/diataxis/references/map.rst new file mode 120000 index 0000000..9d027ef --- /dev/null +++ b/skills/diataxis/references/map.rst @@ -0,0 +1 @@ +../../../map.rst \ No newline at end of file diff --git a/skills/diataxis/references/quality.rst b/skills/diataxis/references/quality.rst new file mode 120000 index 0000000..91420e8 --- /dev/null +++ b/skills/diataxis/references/quality.rst @@ -0,0 +1 @@ +../../../quality.rst \ No newline at end of file diff --git a/skills/diataxis/references/reference-explanation.rst b/skills/diataxis/references/reference-explanation.rst new file mode 120000 index 0000000..87739f6 --- /dev/null +++ b/skills/diataxis/references/reference-explanation.rst @@ -0,0 +1 @@ +../../../reference-explanation.rst \ No newline at end of file diff --git a/skills/diataxis/references/reference.rst b/skills/diataxis/references/reference.rst new file mode 120000 index 0000000..68a8fd0 --- /dev/null +++ b/skills/diataxis/references/reference.rst @@ -0,0 +1 @@ +../../../reference.rst \ No newline at end of file diff --git a/skills/diataxis/references/start-here.rst b/skills/diataxis/references/start-here.rst new file mode 120000 index 0000000..ffdcd81 --- /dev/null +++ b/skills/diataxis/references/start-here.rst @@ -0,0 +1 @@ +../../../start-here.rst \ No newline at end of file diff --git a/skills/diataxis/references/theory.rst b/skills/diataxis/references/theory.rst new file mode 120000 index 0000000..6cd5f3c --- /dev/null +++ b/skills/diataxis/references/theory.rst @@ -0,0 +1 @@ +../../../theory.rst \ No newline at end of file diff --git a/skills/diataxis/references/tutorials-how-to.rst b/skills/diataxis/references/tutorials-how-to.rst new file mode 120000 index 0000000..7d1eefb --- /dev/null +++ b/skills/diataxis/references/tutorials-how-to.rst @@ -0,0 +1 @@ +../../../tutorials-how-to.rst \ No newline at end of file diff --git a/skills/diataxis/references/tutorials.rst b/skills/diataxis/references/tutorials.rst new file mode 120000 index 0000000..c94fcce --- /dev/null +++ b/skills/diataxis/references/tutorials.rst @@ -0,0 +1 @@ +../../../tutorials.rst \ No newline at end of file