diataxis-writing

# 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:**

```bash
# 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](references/compass.md) to determine document type
2. **Select Template** - Choose the corresponding template from [templates/](templates/)
3. **Apply Checklist** - Use the corresponding [checklist](references/) during writing
4. **Quality Assessment** - Use the [quality framework](references/quality-framework.md) 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, corres...

# Diataxis Writing Skill

A comprehensive skill for creating high-quality documentation using the Diataxis framework.

## Overview

This skill provides complete guidance for creating documentation based on the [Diataxis framework](https://diataxis.fr), including:

- **Four documentation types**: Tutorial, How-to Guide, Reference, Explanation
- **Decision tools**: Diataxis Compass for type selection
- **Templates**: 8 scenario-based templates
- **Checklists**: Quality checklists for each type
- **Diagnosis tools**: Automatic document type detection

## Installation

### For OpenClaw Users

Copy this skill to your workspace:

```bash
cp -r diataxis-writing /root/.openclaw/workspace/skills/
```

### Requirements

- Python 3.8+
- Node.js 18+ (for MCPorter integration)

## Usage

The skill automatically triggers when you mention:

- Documentation creation or writing tasks
- Diataxis framework
- Document type selection
- Troubleshooting records
- Experience summaries
- Learning notes
- Best practices
- Technical sharing

### Example Triggers

- "Help me write a tutorial"
- "What type of documentation should this be?"
- "Create a how-to guide for..."
- "Check my documentation structure"

## Project Structure

```
diataxis-writing/
├── SKILL.md              # Core skill guide
├── CHANGELOG.md          # Version history
├── .gitignore           # Git ignore rules
│
├── checklist/           # Quality checklists (4 files)
├── references/          # Theoretical references (7 files)
├── templates/           # Documentation templates (8 files)
└── scripts/             # Helper scripts (2 files)
```

## Features

### 1. Type Diagnosis

Automatically identifies the appropriate documentation type using the Diataxis Compass.

### 2. Templates

8 scenario-based templates:
- Tutorial
- How-to Guide
- Reference
- Explanation
- Troubleshooting
- Best Practices
- Learning Notes
- Exploratory Sharing

### 3. Checklists

Quality checklists for each documentation type to ensure consistency a...