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

技术文档写作

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

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

这篇文章会带你学什么？

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

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

---

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

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

::: tip 好文档的价值

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

---

1. 文档的类型与结构

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

1.1 常见文档类型

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

1.2 README 的黄金结构

一个好的 README 应该包含：

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

---

2. 写作原则

2.1 清晰优先

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

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

2.2 面向读者

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

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

2.3 代码示例是最好的文档

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

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

---

3. 实战对比

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

3.1 Commit Message 规范

# 差
fix bug
update code

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

3.2 注释的艺术

// 差：描述"是什么"（代码已经说了）
// 遍历数组
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 开始。