test-repo/docs/zh-cn/appendix/9-engineering-excellence/technical-writing.md

# 技术文档写作

::: tip 前言
**你写的文档有人看吗？** 很多开发者觉得"代码能跑就行，文档以后再说"。结果就是：新人入职看不懂项目、API 对接全靠口头沟通、半年后自己都忘了当初为什么这么设计。

本章带你掌握技术文档写作的核心方法，让你的文档真正有人看、看得懂、用得上。
:::

**这篇文章会带你学什么？**

| 章节 | 内容 | 核心概念 |
|-----|------|---------|
| **第 1 章** | 文档的类型与结构 | 不同文档的写法 |
| **第 2 章** | 写作原则 | 清晰、准确、简洁 |
| **第 3 章** | 实战对比 | 好文档 vs 差文档 |
| **第 4 章** | 文档维护 | 让文档保持更新 |

学完本章，你将能写出结构清晰、内容准确、易于维护的技术文档。

---

## 0. 全景图：为什么技术文档重要？

代码告诉计算机"怎么做"，文档告诉人类"为什么这么做"。没有文档的项目就像没有说明书的电器——能用，但用起来全靠猜。

::: tip 好文档的价值
- **降低沟通成本**：新人自助上手，减少重复解答
- **保存决策上下文**：记录"为什么"，而不只是"是什么"
- **提升项目可信度**：好文档是开源项目的门面
- **加速协作**：API 文档让前后端并行开发
:::

---

## 1. 文档的类型与结构

通过下面的交互组件，了解不同类型文档的标准结构：

<DocStructureDemo />

### 1.1 常见文档类型

| 文档类型 | 目标读者 | 核心内容 |
|---------|---------|---------|
| **README** | 所有人 | 项目是什么、怎么用、怎么贡献 |
| **API 文档** | 接口调用方 | 端点、参数、响应、错误码 |
| **架构文档** | 开发团队 | 系统设计、技术选型、数据流 |
| **变更日志** | 用户/开发者 | 版本变化、新增/修复/破坏性变更 |
| **贡献指南** | 贡献者 | 开发环境、代码规范、PR 流程 |

### 1.2 README 的黄金结构

一个好的 README 应该包含：

1. **项目名称 + 一句话描述**：让人 3 秒内知道这是什么
2. **快速开始**：最少步骤跑起来
3. **功能特性**：核心卖点
4. **安装方式**：详细的环境要求和安装步骤
5. **使用示例**：可复制粘贴的代码
6. **贡献指南**：如何参与
7. **许可证**：法律信息

---

## 2. 写作原则

### 2.1 清晰优先

```markdown
<!-- 差：模糊不清 -->
这个函数处理数据。

<!-- 好：具体明确 -->
将原始订单数据转换为发票格式，包含税费计算和币种转换。
```

### 2.2 面向读者

写文档前先问：**谁会读这个文档？他们需要什么信息？**

- 给新手写：解释术语，提供完整示例
- 给有经验的开发者写：直奔主题，提供 API 参考
- 给非技术人员写：用类比，避免术语

### 2.3 代码示例是最好的文档

```markdown
<!-- 差：只有文字描述 -->
调用 createUser 函数，传入用户名和邮箱参数。

<!-- 好：给出可运行的示例 -->
const user = await createUser({
  name: '张三',
  email: 'zhangsan@example.com'
})
// 返回: { id: 'u_123', name: '张三', createdAt: '2025-01-15' }
```

---

## 3. 实战对比

通过下面的交互组件，对比好的技术写作和差的技术写作：

<TechWritingPracticeDemo />

### 3.1 Commit Message 规范

```
# 差
fix bug
update code

# 好（Conventional Commits）
fix: 修复登录页在 Safari 下白屏的问题
feat: 支持批量导出 PDF 格式报表
docs: 更新 API 认证章节的示例代码
```

### 3.2 注释的艺术

```javascript
// 差：描述"是什么"（代码已经说了）
// 遍历数组
for (const item of items) { ... }

// 好：解释"为什么"
// 倒序遍历，因为删除元素时正序会跳过下一个
for (let i = items.length - 1; i >= 0; i--) { ... }
```

---

## 4. 文档维护

### 4.1 文档即代码

把文档和代码放在同一个仓库，用同样的工作流管理：

- 文档变更随代码一起提交 PR
- CI 检查文档格式和链接有效性
- 版本发布时同步更新文档

### 4.2 避免文档腐烂

| 问题 | 解决方案 |
|------|---------|
| 文档过时 | 代码变更时强制更新文档（PR 检查） |
| 无人维护 | 指定文档负责人 |
| 内容重复 | 单一信息源，其他地方引用链接 |

---

## 5. 总结

1. **类型匹配**：不同文档有不同的结构和写法
2. **清晰优先**：具体、准确、面向读者
3. **示例驱动**：好的代码示例胜过千言万语
4. **持续维护**：文档即代码，随项目一起演进

::: tip 终极思考
写文档不是浪费时间，而是**节省未来的时间**。你今天花 30 分钟写的文档，可能帮 10 个人各节省 1 小时。好的文档是对团队最好的投资。
:::

---

## 延伸阅读

- **写作指南**：Google 的技术写作课程（Technical Writing）免费且实用。
- **文档工具**：VitePress、Docusaurus、GitBook 等现代文档框架。
- **API 文档**：OpenAPI/Swagger 规范是 API 文档的行业标准。
- **实践建议**：从给自己的项目写一个好的 README 开始。