name: 技术写作 description: 用于软件项目的专业技术文档写作，包括README文件、用户指南、迁移指南、变更日志、API文档、错误消息、发布说明和开发者文档。涵盖文档风格、语气、声音、清晰度、简洁性以及面向受众的写作。触发器：技术写作、文档、文档、README、指南、教程、变更日志、迁移指南、编写文档、文档代码、文档风格、写作指南、语气、声音、清晰度、简洁性、用户文档、开发者文档、API写作、API文档、错误消息、发布说明、技术沟通、为开发者写作、文档标准。

技术写作

概述

全面的技术写作技能，覆盖所有软件文档需求：用户指南、开发者文档、API参考、错误消息、发布说明、迁移指南和README文件。提供文档风格、语气、清晰度和面向受众沟通的专业知识。

指令

1. 文档编写前先理解

先阅读代码：从不编写文档而不理解实现
识别目的：这段代码解决什么问题？
跟踪流程：理解组件如何交互
注意边缘情况：记录限制和约束
检查现有文档：回顾当前文档的风格和差距

2. 了解您的受众

开发者：专注于API细节、代码示例、技术深度、实现模式
最终用户：专注于任务、结果、最小化技术术语、清晰指令
操作员/DevOps：专注于部署、配置、监控、故障排除
新团队成员：专注于入职培训、架构概述、概念理解
开源贡献者：专注于贡献工作流程、代码标准、测试要求

3. 有效结构化文档

标准文档结构：

1. 概述/介绍
   - 这是什么？
   - 为什么存在？
   - 为谁设计？

2. 入门指南
   - 先决条件
   - 安装
   - 快速开始示例

3. 核心概念
   - 关键术语
   - 架构概述
   - 心智模型

4. 使用指南
   - 常见任务
   - 配置选项
   - 最佳实践

5. API参考
   - 方法/端点
   - 参数
   - 返回值
   - 示例

6. 故障排除
   - 常见问题
   - 错误消息
   - FAQ

7. 贡献（如果适用）
   - 开发设置
   - 代码风格
   - PR流程

4. 写作流程

先起草大纲：在写正文前创建结构
撰写草稿：不追求完美，先写内容
添加示例：包含工作代码片段
审查清晰度：简化复杂句子
检查一致性：验证术语和风格
测试示例：确保代码样本工作

最佳实践

文体风格

主动语态：“函数返回”，而不是“值被函数返回”
简洁性：移除不必要的词。“使用X”，而不是“如果你想要，可以使用X”
具体性：“返回字符串”，而不是“返回结果”
现在时态：用于描述和当前行为
祈使语气：用于指令：“运行命令”，而不是“您应该运行”
平行结构：保持列表项语法一致
避免犹豫：“此功能执行X”，而不是“此功能可能执行X”
前置信息：开头说明最重要点

README最佳实践

# 项目名称

简短单行描述。

## 功能

- 关键功能1
- 关键功能2

## 安装

\`\`\`bash
npm install package-name
\`\`\`

## 快速开始

\`\`\`javascript
import { feature } from 'package-name';

const result = feature.doSomething();
\`\`\`

## 文档

链接到完整文档。

## 贡献

链接到贡献指南。

## 许可证

MIT

变更日志最佳实践

遵循Keep a Changelog格式：

# 变更日志

## [未发布]

## [1.2.0] - 2024-01-15

### 新增

- 新功能X用于执行Y

### 更改

- 更新依赖Z到版本2.0

### 修复

- 导致B的bug A

### 移除

- 弃用方法`oldMethod()`

迁移指南最佳实践

# 迁移指南：从v1.x到v2.0

## 概述

简要描述为什么需要迁移。

## 重大变更

### 变更1：新身份验证

**之前（v1.x）：**
\`\`\`javascript
client.auth(apiKey);
\`\`\`

**之后（v2.0）：**
\`\`\`javascript
client.authenticate({ key: apiKey, type: 'bearer' });
\`\`\`

## 逐步迁移

1. 更新包到v2.0
2. 替换身份验证调用（见上）
3. 更新配置文件格式
4. 测试您的集成

## 弃用时间线

- v2.0：旧方法弃用并显示警告
- v3.0：旧方法移除

错误消息最佳实践

错误消息应可操作、具体和尊重：

结构：

发生了什么（错误）
为什么发生（原因）
如何做（解决方案）

良好错误消息：

错误：在'/config.json'找不到配置文件

应用程序在当前目录中查找config.json。

修复方法：
- 在项目根目录创建config.json文件，或
- 使用--config标志指定自定义路径

示例：myapp --config /path/to/config.json

不良错误消息：

错误：空引用异常
无效输入
出错

指南：

具体说明失败内容
对面向用户的错误避免技术术语
提供可操作的下一步
在有用时包括示例
不责备用户（“您犯了错误”）
使用中性语气（“未找到文件”，而不是“您未提供文件”）

发布说明最佳实践

发布说明以可扫描、优先排序的格式向用户传达变更：

# 发布v2.5.0 - 2026年1月

## 亮点

简要段落总结最重要变更及其影响。

## 新功能

### 功能名称

简要描述功能作用和用户关注点。

使用示例：
\`\`\`bash
command --new-flag value
\`\`\`

**谁应使用此功能**：管理大型代码库的团队

### 其他功能

描述和示例。

## 改进

- **性能**：大型数据集的数据库查询现在快3倍
- **用户体验**：仪表板现在增量加载以改善感知性能
- **API**：在REST API中添加对批处理操作的支持

## 错误修复

- 修复处理含Unicode字符文件时的崩溃
- 修复时区跨越午夜时报告中的不正确总计
- 修复长时间运行后台作业中的内存泄漏

## 重大变更

### 更改身份验证流程

**影响**：所有API客户端必须更新身份验证代码

**之前：**
\`\`\`javascript
client.authenticate(token);
\`\`\`

**之后：**
\`\`\`javascript
client.authenticate({ token, type: 'bearer' });
\`\`\`

**迁移截止日期**：v3.0（6个月）

## 弃用

- `oldMethod()`已弃用。使用`newMethod()`代替。
- 对Node 14的支持将在v3.0移除

## 升级指令

1. 备份您的数据
2. 更新到v2.5.0：`npm install package@2.5.0`
3. 运行迁移脚本：`npm run migrate`
4. 更新身份验证代码（见重大变更）
5. 测试您的集成

## 已知问题

- 在Safari 15上仪表板可能慢（计划在v2.5.1修复）
- 在Windows上导出到PDF不工作（解决方法：导出到CSV）

指南：

开头说明用户影响，而非实现细节
按类型分组（功能、修复、重大变更）
为重大变更提供迁移路径
包括变更API的代码示例
指定版本号和时间线
诚实承认已知问题

为开发者写作

开发者文档需要技术深度和清晰度：

API文档结构：

## 方法名称

简要单行描述此方法作用。

### 签名

\`\`\`typescript
functionName(param1: Type1, options?: Options): ReturnType
\`\`\`

### 参数

| 参数 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `param1` | `string` | 是 | 主要输入值 |
| `options` | `Object` | 否 | 配置选项（下） |

#### 选项

| 选项 | 类型 | 默认 | 描述 |
| --- | --- | --- | --- |
| `timeout` | `number` | `5000` | 请求超时（毫秒） |
| `retries` | `number` | `3` | 重试次数 |

### 返回

返回`Promise<Result>`，解析为：

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `success` | `boolean` | 操作是否成功 |
| `data` | `any` | 成功时的响应数据 |
| `error` | `string` | 失败时的错误消息 |

### 错误

| 错误代码 | 条件 | 解决方案 |
| --- | --- | --- |
| `TIMEOUT` | 请求超过超时 | 增加超时值 |
| `INVALID` | 参数验证失败 | 检查参数类型 |

### 示例

基本使用：
\`\`\`typescript
const result = await functionName('input-value');
if (result.success) {
console.log(result.data);
}
\`\`\`

带选项：
\`\`\`typescript
const result = await functionName('input-value', {
timeout: 10000,
retries: 5
});
\`\`\`

错误处理：
\`\`\`typescript
try {
const result = await functionName('input-value');
} catch (error) {
if (error.code === 'TIMEOUT') {
// 处理超时
}
}
\`\`\`

### 备注

- 此方法速率限制为每分钟100次调用
- 需要API密钥身份验证
- 从版本2.0开始可用

架构文档：

包括图表（ASCII艺术、mermaid或图像引用）
解释设计决策的“为什么”
记录权衡和考虑的替代方案
为未来维护者提供上下文
链接到相关ADR（架构决策记录）

代码注释（需要时）：

解释“为什么”，而非“什么”（代码显示什么）
记录非明显行为
解释变通方法或黑客
引用问题/票据以提供上下文
保持注释与代码变更同步

示例

示例：函数文档

/**
 * 计算包括税和折扣的总价。
 *
 * @param {number} basePrice - 调整前的原始价格
 * @param {Object} options - 计算选项
 * @param {number} [options.taxRate=0.1] - 税率作为小数（0.1 = 10%）
 * @param {number} [options.discount=0] - 折扣金额，以货币单位计
 * @returns {number} 最终价格，四舍五入到2位小数
 * @throws {Error} 如果basePrice为负数
 *
 * @example
 * // 基本使用
 * calculateTotal(100);
 * // 返回：110.00
 *
 * @example
 * // 带折扣
 * calculateTotal(100, { discount: 20 });
 * // 返回：88.00
 */
function calculateTotal(basePrice, options = {}) {
  // 实现
}

示例：CLI文档

## 使用

\`\`\`
myapp <command> [options]
\`\`\`

### 命令

| 命令 | 描述 |
| --- | --- |
| `init` | 初始化新项目 |
| `build` | 构建项目 |
| `serve` | 启动开发服务器 |

### 选项

| 选项 | 别名 | 描述 | 默认 |
| --- | --- | --- | --- |
| `--config` | `-c` | 配置文件路径 | `./config.json` |
| `--verbose` | `-v` | 启用详细输出 | `false` |
| `--port` | `-p` | 服务器端口 | `3000` |

### 示例

初始化新项目：
\`\`\`bash
myapp init my-project
\`\`\`

使用自定义配置构建：
\`\`\`bash
myapp build -c ./custom-config.json
\`\`\`