technical-writing

技术写作技能

适用于任何用户项目的自包含技术文档专业知识。

擅长面向开发者的文档：README、API 参考、教程和变更日志。

---

核心文档类型

1. README 文件

基本结构：

# Project Name

One-sentence description.

## Features
- Key feature 1
- Key feature 2

## Installation
```bash
npm install project-name

快速开始

import { ProjectName } from 'project-name';
const instance = new ProjectName();

用法

[基本示例]

API 参考

[链接或内联参考]

贡献

[链接到 CONTRIBUTING.md]

许可证

MIT

**Best Practices**:
- Lead with value (what problem solved?)
- Code examples > long explanations
- Progressive disclosure (quick start → advanced)
- Keep updated with code

### 2. API Documentation

**Function/Method Documentation**:
```typescript
/**
 * Compress image with quality settings
 *
 * @param {string} input - Path to input image
 * @param {CompressOptions} options - Compression options
 * @param {number} options.quality - Quality 0-100 (default: 80)
 * @param {string} options.format - Output format: jpeg|png|webp
 *
 * @returns {Promise<CompressResult>} Compression result with saved bytes
 *
 * @example
 * const result = await compress('photo.jpg', { quality: 90 });
 * console.log(`Saved ${result.savedBytes} bytes`);
 */

REST API 文档：

### POST /api/users

Create a new user.

**Request**:
```json
{
  "email": "[email protected]",
  "name": "John Doe"
}

响应（201 Created）：

{
  "id": "uuid",
  "email": "[email protected]",
  "name": "John Doe",
  "created": "2025-11-24T12:00:00Z"
}

错误：

• 400：电子邮件格式无效
• 409：电子邮件已存在

### 3. Tutorials

**Structure**:
```markdown
# Tutorial: Build X in 10 Minutes

**You'll learn**:
- How to set up X
- Core concepts
- Build a working example

**Prerequisites**:
- Node.js 18+
- Basic JavaScript knowledge

## Step 1: Setup

```bash
npm create vite@latest my-project
cd my-project
npm install

第 2 步：创建组件

[附带说明的代码]

第 3 步：测试

[如何运行和验证]

后续步骤

• 高级功能 1
• 高级功能 2
• API 文档链接

**Best Practices**:
- State prerequisites up front
- Break into small, testable steps
- Show expected output at each step
- Link to related docs

### 4. Changelogs

**Keep a Changelog Format** (keepachangelog.com):
```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New feature X for Y use case

### Changed
- Improved performance of Z by 40%

### Fixed
- Critical bug in authentication (CVE-2024-1234)

## [1.2.0] - 2025-11-24

### Added
- Real-time notifications via WebSocket
- Export to PDF functionality

### Changed
- Updated dependencies (React 19)

### Deprecated
- `oldMethod()` - use `newMethod()` instead

### Removed
- Legacy API v1 endpoints

### Fixed
- Memory leak in image processing
- CORS issue with production domain

### Security
- Fixed SQL injection vulnerability (CVE-2025-5678)

## [1.1.0] - 2025-11-01

[Previous release notes]

类别：

• 新增：新功能
• 变更：现有功能的变更
• 弃用：即将移除的功能
• 移除：已移除的功能
• 修复：错误修复
• 安全：漏洞修复

---

风格指南要点

语态与语气

主动语态（推荐）：

• ✅ “该函数返回一个数组”
• ❌ “一个数组由该函数返回”

现在时（推荐）：

• ✅ “API 验证输入”
• ❌ “API 将验证输入”

第二人称（用于教程）：

• ✅ “你可以配置超时时间”
• ❌ “用户可以配置超时时间”

清晰度规则

具体明确：

• ✅ “将超时时间设为 5000ms”
• ❌ “设置一个合理的超时时间”

避免行话（或加以解释）：

• ✅ “幂等（可安全地多次调用）”
• ❌ “该端点是幂等的”

使用短句：

• ✅ “安装软件包。然后导入它。”
• ❌ “安装软件包后，你需要将它导入项目。”

代码示例

展示完整示例：

// ✅ GOOD - Complete, runnable
import { connect } from 'database';

const db = await connect({
  host: 'localhost',
  port: 5432
});

const users = await db.query('SELECT * FROM users');
console.log(users);

// ❌ BAD - Incomplete
db.query('SELECT * FROM users');

包含错误处理：

// ✅ GOOD
try {
  const result = await processImage('photo.jpg');
  console.log('Success:', result);
} catch (error) {
  console.error('Failed to process image:', error.message);
}

---

文档结构

信息架构

按用户旅程组织：

docs/
├── getting-started/
│   ├── installation.md
│   ├── quick-start.md
│   └── first-project.md
├── guides/
│   ├── authentication.md
│   ├── deployment.md
│   └── troubleshooting.md
├── api-reference/
│   ├── client.md
│   ├── server.md
│   └── types.md
└── examples/
    ├── basic-crud.md
    ├── real-time-updates.md
    └── advanced-queries.md

渐进式呈现：

1. 入门：最快获得价值的路径
2. 指南：以任务为导向的操作说明
3. API 参考：完整的技术参考
4. 示例：真实场景中的模式

导航最佳实践

清晰的层级：

• 使用一致的标题级别（H1 → H2 → H3）
• 不要跳过标题级别
• 每页只使用一个 H1

交叉链接：

• 链接到相关文档
• 链接到前置要求
• 链接到后续步骤

目录（适用于长页面）：

## Table of Contents

- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [Basic Example](#basic-example)
  - [Advanced Example](#advanced-example)
- [API Reference](#api-reference)

---

OpenAPI / Swagger

OpenAPI 3.0 模板

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: User management API

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string

    CreateUser:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string

---

文档维护

版本策略

让文档与代码版本保持一致：

docs/
├── v1.0/
│   ├── api.md
│   └── guides.md
├── v2.0/
│   ├── api.md
│   ├── guides.md
│   └── migration.md
└── latest/ → symlink to v2.0/

迁移指南：

# Migrating from v1 to v2

## Breaking Changes

### Authentication

**v1**:
```javascript
const api = new API({ token: 'abc123' });

v2：

const api = new API({
  auth: { bearer: 'abc123' }
});

变更内容

• token 参数已重命名为 auth.bearer
• 现在支持多种身份验证方法

迁移步骤

1. 更新 API 初始化
2. 测试身份验证流程
3. 更新错误处理（新的错误代码）

### Keep Docs Fresh

**Automation**:
- Generate API docs from code (JSDoc, TypeDoc, OpenAPI)
- Auto-update version numbers in docs
- CI/CD checks for broken links

**Review Checklist**:
- [ ] Code examples run without errors
- [ ] All links work (no 404s)
- [ ] Version numbers match package.json
- [ ] Screenshots show current UI
- [ ] Deprecation warnings added for old features

---

## Common Pitfalls

**❌ Avoid**:
- Outdated examples (don't run)
- Missing prerequisites
- Incomplete code snippets
- Vague error messages ("something went wrong")
- Over-explaining obvious things
- Using future tense ("will do X")

**✅ Do**:
- Test all code examples
- State prerequisites up front
- Show complete, runnable code
- Specific error messages with fixes
- Respect reader's intelligence
- Use present tense

---

## Quick Reference Templates

### Function Documentation
```javascript
/**
 * Brief description
 *
 * @param {Type} paramName - Description
 * @returns {Type} Description
 * @throws {ErrorType} When/why
 * @example
 * functionName(arg);
 */

CLI 命令文档

### command [options]

Description of what command does.

**Options**:
- `-f, --flag`: Description (default: value)
- `-o, --option <value>`: Description

**Examples**:
```bash
command --flag --option=value

### Error Documentation
```markdown
### Error: ECONNREFUSED

**Cause**: Cannot connect to database

**Solutions**:
1. Check database is running: `docker ps`
2. Verify connection string in `.env`
3. Check firewall allows port 5432

---

此技能自包含，适用于任何用户项目。