Diataxis Writing

---

name: diataxis-writing description: Diataxis documentation framework practice guide. Provides diagnosis, classification, templates, and quality assessment for four documentation types (Tutorial/How-to/Reference/Explanation).

---

Diátaxis Documentation Framework Practice

Quick Start

When creating or refactoring documentation:

Pre-Writing Questions (Must Ask)

Before starting, ask the user:

1. Language Preference: "What language should this document be written in?" - English / 中文 / Other

2. 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 --detect

Check 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.json or ~/.mcporter/mcporter.json)

Test connection to Feishu MCP server

If tool not available: 1. Inform user: "Selected output method [X] is not available" 2. Suggest alternatives: "Available options: [list]" 3. Ask user to confirm alternative or configure tool

Writing Workflow

After confirming language, output preference, and tool availability:

1. Identify User Needs - Use the Diataxis Compass to determine document type 2. Select Template - Choose the corresponding template from templates/ 3. Apply Checklist - Use the corresponding checklist during writing 4. Quality Assessment - Use the quality framework to evaluate the final draft 5. 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: 1. Content Type: Is it action guidance (action) or cognitive knowledge (cognition)? 2. 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

1. Type Conflation - Mixing Reference content into Tutorial 2. Misplacement - Writing Explanation as Tutorial 3. Boundary Blur - Mixing too much explanation into How-to 4. 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

1. Chat Message - Display directly in conversation (default) 2. Feishu Document - Create/update Feishu document via MCP/mcporter (requires MCP feishu server) 3. Local Markdown - Save as .md file (built-in support) 4. GitHub Repo - Commit to code repository (requires MCP github or git) 5. 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 --detect

Tool Availability Check

After user selects output method, check if tool is available:

1. Run output-handler.py --detect 2. Check if selected tool is configured and available 3. 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 write tool or output-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 

---

Skill Version: 1.0 Theory Source: https://diataxis.fr Author: Zhua Zhua (Created for Master)

When creating or refactoring documentation:

Pre-Writing Questions (Must Ask)

Before starting, ask the user:

1. Language Preference: "What language should this document be written in?" - English / 中文 / Other

2. 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 --detect

Check 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.json or ~/.mcporter/mcporter.json)

Test connection to Feishu MCP server

If tool not available: 1. Inform user: "Selected output method [X] is not available" 2. Suggest alternatives: "Available options: [list]" 3. Ask user to confirm alternative or configure tool

Writing Workflow

After confirming language, output preference, and tool availability:

1. Identify User Needs - Use the Diataxis Compass to determine document type 2. Select Template - Choose the corresponding template from templates/ 3. Apply Checklist - Use the corresponding checklist during writing 4. Quality Assessment - Use the quality framework to evaluate the final draft 5. Execute Output - Output using the user's chosen method and language