documentation-writing

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

---
name: documentation-writing
description: Comprehensive guide for writing technical documentation including README files, API docs, user guides, architecture docs, and more. Use when creating or improving any form of documentation for software projects.
---

# Documentation Writing Skill

## When to Use This Skill

Use this skill when:

- Writing README files for projects
- Creating API documentation
- Writing user guides and tutorials
- Documenting architecture and design decisions
- Creating onboarding documentation
- Writing code comments and inline docs
- Developing knowledge base articles
- Creating changelogs and release notes

## Core Documentation Principles

### The 4 Types of Documentation

1. **Tutorials** - Learning-oriented (teaching)
   - Takes user through a series of steps
   - Helps beginners get started
   - Example: "Building Your First React App"

2. **How-To Guides** - Task-oriented (problem-solving)
   - Solves a specific problem
   - Assumes some knowledge
   - Example: "How to Add Authentication"

3. **Explanations** - Understanding-oriented (clarifying)
   - Explains concepts and context
   - Provides background knowledge
   - Example: "Understanding JWT Tokens"

4. **Reference** - Information-oriented (facts)
   - Technical descriptions
   - Accurate and complete
   - Example: "API Endpoint Reference"

### Writing Best Practices

**Clarity**

- Use simple, direct language
- Avoid jargon unless necessary
- Define technical terms on first use
- Use active voice: "Click the button" not "The button should be clicked"
- One idea per sentence

**Structure**

- Start with most important information
- Use headings to organize content
- Keep paragraphs short (3-5 sentences)
- Use lists for multiple items
- Add visual hierarchy

**Completeness**

- Answer who, what, when, where, why, and how
- Include prerequisites
- Provide examples
- Link to related documentation
- Include error handling

**Accuracy**

- Test all code examples
- Keep documentation updated with code
- Include version information
- Verify links work

## README File Templates

### Minimal README (Small Projects)

````markdown
# Project Name

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

## Installation

```bash
npm install project-name
```
````

## Usage

```javascript
const project = require("project-name");
project.doSomething();
```

## License

MIT

````

### Standard README (Most Projects)
```markdown
# Project Name

[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]
[![License](https://img.shields.io/badge/license-MIT-blue)]
[![Version](https://img.shields.io/badge/version-1.0.0-blue)]

Brief description of what this project does and why it exists.

## Features

- Feature one
- Feature two
- Feature three

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [API Documentation](#api-documentation)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)

## Installation

### Prerequisites

- Node.js 18+
- npm or yarn
- PostgreSQL 14+

### Install Dependencies

```bash
npm install
````

### Environment Setup

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

Required environment variables:

```
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
API_KEY=your_api_key_here
PORT=3000
```

## Quick Start

```bash
# Install dependencies
npm install

# Run development server
npm run dev

# Visit http://localhost:3000
```

## Usage

### Basic Example

```javascript
const { Client } = require("project-name");

const client = new Client({
  apiKey: "your-api-key",
});

await client.connect();
const result = await client.getData();
console.log(result);
```

### Advanced Example

```javascript
const client = new Client({
  apiKey: "your-api-key",
  timeout: 5000,
  retries: 3,
});

client.on("error", (error) => {
  console.error("Connection error:", error);
});

const data = await client.ge