Diátaxis Documentation Framework Practice
Quick Start
When creating or refactoring documentation:
Pre-Writing Questions (Must Ask)
Before starting, ask the user:
- Language Preference: "What language should this document be written in?"
- English / 中文 / Other
- Output Method: "After completion, how would you like to output this document?"
- Chat message (default) - Feishu document (via MCP/mcporter) - Local Markdown file - GitHub repository - Other platforms
Tool Availability Check (After User Selection)
After user selects output method, automatically check tool availability:
# Run auto-detection (script is in ./scripts/ relative to this skill)
python3 scripts/output-handler.py --detectCheck results:
- ✅ Tool available → Proceed with selected output method
- ⚠️ Tool not available → Inform user and suggest alternatives
For Feishu output via MCP:
- Check if mcporter is installed
- Check if MCP feishu server is configured (typically in
/root/config/mcporter.jsonor~/.mcporter/mcporter.json) - Test connection to Feishu MCP server
If tool not available:
- Inform user: "Selected output method [X] is not available"
- Suggest alternatives: "Available options: [list]"
- Ask user to confirm alternative or configure tool
Writing Workflow
After confirming language, output preference, and tool availability:
- Identify User Needs - Use the Diataxis Compass to determine document type
- Select Template - Choose the corresponding template from templates/
- Apply Checklist - Use the corresponding checklist during writing
- Quality Assessment - Use the quality framework to evaluate the final draft
- Execute Output - Output using the user's chosen method and language
Four Documentation Types
Diataxis identifies four fundamentally different documentation types, corresponding to four user needs:
| Type | User Need | Document Purpose | Key Characteristics |
|---|---|---|---|
| Tutorial | Acquire skills (study) | Provide learning experience | Practice-oriented, minimize explanation, concrete steps |
| How-to Guide | Apply skills (work) | Help complete tasks | Goal-oriented, assume competence, handle real scenarios |
| Reference | Apply skills (work) | Describe technical facts | Neutral description, accurate and complete, structured |
| Explanation | Acquire skills (study) | Provide understanding context | Discursive, allows opinions, provides context |
Type Details
- Tutorial: references/four-types.md#Tutorial
- How-to Guide: references/four-types.md#How-to Guide
- Reference: references/four-types.md#Reference
- Explanation: references/four-types.md#Explanation
Using the Diataxis Compass
When unsure about document type, use the compass tool: references/compass.md
Ask two questions:
- Content Type: Is it action guidance (action) or cognitive knowledge (cognition)?
- User State: Is the user acquiring skills (acquisition/study) or applying skills (application/work)?
Common Use Cases
Use Case 1: Troubleshooting Records → How-to Guide or Explanation
Troubleshooting records typically belong to:
- How-to Guide: If it's step-by-step guidance on "how to solve X problem"
- Explanation: If it's principle analysis on "why X problem occurred"
Template: templates/template-troubleshooting.md
Use Case 2: Experience Summary → How-to Guide or Explanation
- Best Practices: How-to Guide (guidance on how to do things correctly)
- Lessons Learned: Explanation (explaining why certain approaches are wrong)
Template: templates/template-best-practices.md
Use Case 3: Learning Notes → Tutorial or Explanation
- Learning Notes: Tutorial (if containing practical steps)
- Theory Summary: Explanation (if conceptual understanding)
Template: templates/template-learning-notes.md
Use Case 4: Exploratory Sharing → Explanation
Technical exploration, experiment records, and comparative analysis typically belong to Explanation.
Template: templates/template-exploration.md
Checklists
Use checklists during and after writing:
- Tutorial: checklist/checklist-tutorial.md
- How-to: checklist/checklist-how-to.md
- Reference: checklist/checklist-reference.md
- Explanation: checklist/checklist-explanation.md
Quality Assessment
Use the Functional Quality and Deep Quality framework: references/quality-framework.md
Functional Quality
- Accuracy, completeness, consistency, usability, precision
Deep Quality
- Flow, fitting human needs, beauty, anticipating user needs
Common Mistakes
Avoid the following error patterns: references/common-mistakes.md
- Type Conflation - Mixing Reference content into Tutorial
- Misplacement - Writing Explanation as Tutorial
- Boundary Blur - Mixing too much explanation into How-to
- Structural Misalignment - Reference not reflecting product architecture
Language Style
Four types use different language styles: references/writing-language.md
- Tutorial: "We will...", "Notice...", "Now do X..."
- How-to: "If you want X, do Y", "Refer to X documentation for complete options"
- Reference: "X inherits Y", "Subcommands: a, b, c", "Must use X"
- Explanation: "The reason for X is...", "W is better than Z because..."
Output Methods
After completing the document, output using the user's chosen method:
Available Output Methods
- Chat Message - Display directly in conversation (default)
- Feishu Document - Create/update Feishu document via MCP/mcporter (requires MCP feishu server)
- Local Markdown - Save as.md file (built-in support)
- GitHub Repo - Commit to code repository (requires MCP github or git)
- Other Platforms - User provides platform and MCP capabilities
Important: For Feishu output, always use MCP/mcporter method, NOT channel tools.
Detect Available Tools
Use scripts/output-handler.py to auto-detect (script is in ./scripts/ relative to this skill file):
python3 scripts/output-handler.py --detectTool Availability Check
After user selects output method, check if tool is available:
- Run
output-handler.py --detect - Check if selected tool is configured and available
- If not available:
- Inform user: "Selected output method [X] is not available" - Suggest alternatives from available tools list - Ask user to confirm alternative
Choose Output Method
Must ask user: "Document completed, how would you like to output?"
Based on user selection:
- Chat → Reply directly
- Feishu (MCP) → Use mcporter to call Feishu MCP server
node /path/to/mcporter/dist/cli.js call feishu doc.create '{"title":"...", "content":"..."}' # Note: mcporter path varies by installation, common paths: # - ~/.npm/_npx/*/node_modules/mcporter/dist/cli.js # - Or use: npx mcporter call feishu doc.create... - Local → Call
writetool oroutput-handler.py --output local - GitHub → Call
output-handler.py --output github - Other → Ask user to provide MCP server information
Language Considerations
Output in the user's chosen language:
- If English → Output in English
- If Chinese (中文) → Output in Chinese
- If other → Confirm translation capabilities
Output Platform Details
Complete platform list and configuration methods: references/output-platforms.md
| Platform | Required Tools | Configuration Difficulty | Use Case |
|---|---|---|---|
| Chat | None | - | Quick reply |
| Feishu (MCP) | MCP feishu server | Medium | Team collaboration |
| Local MD | write | Low | Personal knowledge |
| GitHub | MCP github/git | Medium | Tech blog |
| Notion | MCP notion | Medium | Knowledge base |
| Google Docs | MCP google | High | Google ecosystem |
Theoretical Framework
Complete Diataxis theory:
- Map Model: references/map.md
- Theoretical Foundations: references/four-types.md
- Quality Theory: references/quality-framework.md
Using Scripts (Optional)
Use the diagnosis script to automatically identify document types (script is in ./scripts/ relative to this skill):
python3 scripts/diagnose.py <document content or file path>Skill Version: 1.0 Theory Source: https://diataxis.fr Author: Zhua Zhua (Created for Master)