AgentSkillsCN

Diataxis

掌握Diátaxis文档框架的相关知识，以打造高效的技术文档

SKILL.md
--- frontmatter
description: Knowledge about the Diátaxis documentation framework for creating effective technical documentation
triggers:
  - documentation
  - docs
  - tutorial
  - how-to
  - reference
  - explanation
  - guide

Diátaxis Documentation Framework

This skill provides comprehensive knowledge about the Diátaxis framework for organizing and writing technical documentation.

Overview

Diátaxis identifies four distinct documentation types, each serving different user needs:

TypeOrientationPurposeUser Need
TutorialsLearningTeach through doing"I want to learn"
How-to GuidesTaskSolve specific problems"I want to accomplish X"
ReferenceInformationDescribe the machinery"I need to know Y"
ExplanationUnderstandingClarify concepts"I want to understand Z"

The Four Quadrants

Tutorials (Learning-Oriented)

  • •Purpose: Help beginners learn by doing
  • •Approach: Step-by-step lessons with guaranteed outcomes
  • •Focus: The learner's experience
  • •Goal: Build confidence and basic competence

How-to Guides (Task-Oriented)

  • •Purpose: Help practitioners accomplish specific tasks
  • •Approach: Direct, practical instructions
  • •Focus: The problem to solve
  • •Goal: Successfully complete a task

Reference (Information-Oriented)

  • •Purpose: Describe the system accurately
  • •Approach: Technical, austere, consistent
  • •Focus: The machinery itself
  • •Goal: Provide accurate information quickly

Explanation (Understanding-Oriented)

  • •Purpose: Illuminate concepts and context
  • •Approach: Discursive, reflective
  • •Focus: Understanding why
  • •Goal: Deepen knowledge

Key Principles

  1. •Don't mix types - Each document should be one type only
  2. •Know your audience - Tutorials for learners, how-tos for practitioners
  3. •Serve user needs - Match content type to what users are trying to do
  4. •Maintain clear navigation - Help users find the right type of content

Common Mistakes

  • •Tutorial that becomes a how-to (loses teaching focus)
  • •Reference that includes tutorial content (confuses purpose)
  • •How-to that explains too much (slows down task completion)
  • •Explanation mixed into reference (dilutes both)

References