技术文档写作（Technical Documentation）
概述
代码告诉机器做什么，文档告诉人类为什么。没有文档的项目，新人要花三倍时间上手；没有 README 的仓库，没人愿意尝试你的库。本技能覆盖日常开发中最常见的文档类型及其写作标准。
何时使用
- 为开源项目编写 README
- 撰写 API 接口文档
- 记录架构决策（ADR）
- 编写新人入职指南
- 审查文档质量
文档类型总览
| 类型 | 目标读者 | 核心问题 |
|---|---|---|
| README | 首次访问者 | 这是什么？怎么用？ |
| API 文档 | 集成开发者 | 怎么调用？参数是什么？ |
| 架构决策记录（ADR） | 团队成员、未来维护者 | 为什么这样设计？ |
| 变更日志（Changelog） | 用户、运维 | 这次发布改了什么？ |
| 入职指南 | 新团队成员 | 怎么搭建开发环境？ |
README 模板
一个完整的 README 应包含以下部分（按顺序）：
- 项目名称 + 徽标（Badge）
- 一句话描述 — 用一句话说清楚项目是什么
- 快速开始（Quickstart） — 3 步以内跑起来
- 安装 — 详细安装步骤
- 使用方法 — 核心功能示例
- 配置 — 可配置项及默认值
- 贡献指南 — 如何参与开发
- 许可证 — 开源协议
原则：读者 30 秒内判断是否需要这个项目，3 分钟内跑通第一个示例。
API 文档结构
每个端点必须包含：
- 端点路径和方法：
POST /api/v1/users - 请求参数：路径参数、查询参数、请求体（含类型和是否必填）
- 请求示例：完整的 curl 或代码示例
- 响应示例：成功响应 + 错误响应各一个
- 错误码列表：可能返回的错误码及处理建议
- 认证说明：是否需要认证、需要什么权限
架构决策记录（ADR）
格式（Architecture Decision Record）：
# ADR-001: 选择 PostgreSQL 作为主数据库
## 状态（Status）
已采纳（Accepted）
## 背景（Context）
项目需要支持复杂查询、事务一致性和 JSON 数据存储...
## 决策（Decision）
采用 PostgreSQL 15，原因是...
## 后果（Consequences）
正面：强事务支持、JSON 查询能力...
负面：运维复杂度高于 SQLite...
ADR 的价值在于记录"为什么"，而不是"是什么"。六个月后回头看代码，ADR 能解释当初的权衡。
写作原则
- 可扫描（Scannable） — 用标题、列表、表格组织内容，不写大段文字
- 示例优先（Example-first） — 先给例子，再解释原理
- 假设读者很忙 — 把最重要的信息放在最前面
- 测试你的示例 — 文档中的每个代码示例都必须能运行
- 展示输入和输出 — 代码示例同时展示输入数据和期望输出
代码示例规范
# 好的示例：展示输入和输出，使用真实数据
response = client.post("/api/v1/users", json={
"name": "Alice Chen",
"email": "alice@example.com"
})
# 输出：{"id": 42, "name": "Alice Chen", "status": "active"}
不要用 foo、bar、test123 这类占位数据，用接近真实场景的数据。
文档维护
- 文档即代码（Docs-as-Code） — 文档和代码放在同一个仓库，同一个 PR
- 标注文档版本 — 文档对应哪个版本的 API / 软件
- 链接到源码 — 关键概念链接到具体的代码文件
- 定期审查 — 每次发版检查文档是否过期
必须做 / 禁止做
必须做（MUST DO）：
- 修改代码时同步更新文档
- README 必须包含快速开始（Quickstart）部分
- 文档中的代码示例必须经过测试
- API 文档提供成功和失败两种响应示例
禁止做（MUST NOT）：
- 写大段不分节的文字（Wall of Text）
- 使用专业术语却不解释
- 让文档和实际实现脱节（文档说 v1，代码已经是 v3）
- 只写"怎么用"不写"为什么这样设计"