documentation-writing

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: documentation-writing
description: Audience-first documentation guidance for READMEs, API docs, architecture docs, and tutorials. Ensures clarity, completeness, and maintainability.
---

# Documentation Writing Skill

## Core Principle

**Write for the reader's context, not the author's understanding.**

Documentation exists to transfer knowledge efficiently. Good documentation anticipates questions, provides context, and guides readers to success. The best documentation makes the next user (or future you) productive without requiring tribal knowledge or guesswork.

**Effective documentation:**
- Meets readers where they are (assumes appropriate background)
- Answers "why" not just "what" and "how"
- Provides working examples
- Stays current with code changes
- Guides readers to success, not just describes features

---

## Documentation Types

Different documentation serves different purposes. Choose the right type for your audience and goal.

### README.md (Project Overview)

**Purpose:** First impression and quick-start guide for new users/contributors

**Audience:**
- New users evaluating the project
- Developers wanting to contribute
- Stakeholders assessing project status

**Must include:**
- What the project does (1-2 sentences)
- Why it exists (problem being solved)
- Quick start (minimal steps to see it working)
- Installation/setup instructions
- Basic usage examples
- Link to fuller documentation
- How to contribute (if open source)
- License information

**Template:**
```markdown
# Project Name

Brief description (1-2 sentences) of what this project does.

## Why This Exists

[Problem statement - what pain point does this solve?]

## Quick Start

```bash
# Minimal steps to get running
npm install
npm start
# Now visit http://localhost:3000
```

## Installation

[Detailed setup instructions]

## Usage

[Basic examples with expected output]

## Documentation

- [API Reference](docs/api.md)
- [Architecture Guide](docs/architecture.md)
- [Contributing Guide](CONTRIBUTING.md)

## License

[License type and link]
```

### API Documentation (Reference)

**Purpose:** Technical reference for developers using the API/library

**Audience:** Developers integrating with your code

**Must include:**
- Function/method signatures
- Parameter types and constraints
- Return types and possible values
- Error conditions and exceptions
- Working code examples
- Performance characteristics (if relevant)

**Template:**
```markdown
## functionName(param1, param2, options)

Brief description of what this function does.

**Parameters:**
- `param1` (string, required): Description of parameter
- `param2` (number, optional, default: 0): Description
- `options` (object, optional): Configuration options
  - `option1` (boolean, default: false): Description
  - `option2` (string, default: 'value'): Description

**Returns:**
- (Promise<Result>): Description of return value

**Throws:**
- `ValidationError`: When param1 is empty
- `NotFoundError`: When resource doesn't exist

**Example:**
```javascript
const result = await functionName('input', 42, {
  option1: true
});
console.log(result); // { status: 'success', data: ... }
```

**Performance:**
- Time complexity: O(n)
- Caches results for 5 minutes
```

### Architecture Documentation (Design)

**Purpose:** Explain system design, patterns, and decisions

**Audience:**
- New team members ramping up
- Developers making changes
- Technical stakeholders reviewing design

**Must include:**
- System overview (components and interactions)
- Key design decisions and rationale
- Data flow diagrams
- Technology choices and tradeoffs
- Scaling considerations
- Security model
- Known limitations

**Template:**
```markdown
# System Architecture

## Overview

[High-level description of system components]

```
[ASCII diagram or mermaid diagram showing components]
User → API Gateway → Service Layer → Database
                   ↓
                Cache Layer
```

## Components

### Component Name
**Purpos