技术文档是团队协作、知识传承和系统演进的基石。高质量的文档不仅能降低沟通成本，还能在人员变动时保护组织的知识资产。本文档定义了技术文档的分类体系、编写原则和具体规范，适用于需求文档、设计文档、API文档、操作手册等各类技术文档的编写。
核心原则：文档的价值不在于篇幅，而在于消除歧义、记录决策、加速上手。写文档的成本远低于因误解而返工的成本。
技术文档按用途和受众可分为以下几类：
| 文档类型 | 核心目的 | 主要受众 | 典型生命周期 | 建议篇幅 |
|---|---|---|---|---|
| 需求文档 | 明确业务目标和验收标准 | 产品经理、开发、测试 | 随需求变更迭代 | 2-5页 |
| 设计文档 | 记录技术决策和架构方案 | 开发团队、架构师 | 随架构演进更新 | 5-15页 |
| API文档 | 定义接口契约和使用方式 | 前后端开发、外部接入方 | 随接口版本更新 | 自动生成+补充 |
| 操作手册 | 指导部署、运维和故障处理 | 运维、SRE、开发人员 | 随环境变化更新 | 按场景拆分 |
| 事故复盘 | 记录故障根因和改进措施 | 全团队 | 一次性，但需可检索 | 3-5页 |
| 决策记录 | 记录技术选型的思考过程 | 当前及未来团队成员 | 随认知更新补充 | 1-3页 |
原则：文档不是写一次就完事的。每类文档都有其自然生命周期，应建立定期 review 机制，过期文档要及时标注或归档。
需求文档的核心目标是消除歧义——让开发、测试、产品对"要做什么"和"做到什么程度算完成"达成一致。
| 要素 | 说明 | 示例 |
|---|---|---|
| 背景与目标 | 为什么要做这个需求，解决什么问题 | "当前对账系统每日凌晨2点启动，高峰期延迟导致下游系统阻塞" |
| 范围边界 | 明确包含什么、不包含什么 | "本期仅改造对账任务调度模块，不涉及对账算法本身" |
| 验收标准 | 可验证的完成定义 | "调度延迟从平均15分钟降至2分钟内" |
| 依赖关系 | 上下游依赖和外部约束 | "依赖消息队列升级至v3.2，预计下周完成" |
| 风险与回滚 | 已知风险和应对预案 | "若灰度期间错误率>0.1%，自动回滚至上一版本" |
对于敏捷团队，推荐采用改进版用户故事格式：
作为 [角色]
我希望 [功能描述]
以便 [业务价值]
验收标准：
1. [可验证的条件1]
2. [可验证的条件2]
约束条件：
- [技术约束/业务约束]
- [合规要求]
容易被忽视但至关重要：
设计文档用于对复杂问题与解决方案形成共识，以更高的前期投入为代价，提高交付结果的确定性。设计文档还能为整个团队和公司提供相对完善的整体视图。
设计文档的重点是描述权衡取舍的点，而非开发手册或介绍。以下情况不需要专门的设计文档：
参考：Google的设计文档实践指出，设计文档应该回答"为什么"而非"怎么做"[1]。
1. 背景与目标（1页）
- 要解决什么问题
- 不解决什么问题（范围边界）
2. 现状分析（1-2页）
- 当前系统架构图
- 痛点和数据支撑
3. 方案对比（核心章节）
- 方案A、B、C的概述
- 各方案的优劣对比矩阵
- 最终选择及理由
4. 详细设计（2-5页）
- 架构图（组件、数据流）
- 关键接口定义
- 数据模型变更
5. 风险与应对（1页）
- 技术风险
- 业务风险
- 回滚方案
6. 实施计划（1页）
- 里程碑
- 依赖项
- 验收标准
API文档是服务端与客户端之间的法律契约，必须精确、完整、可验证。
| 字段 | 说明 | 示例 |
|---|---|---|
| 接口路径 | HTTP方法 + URL | POST /api/v1/payments |
| 功能描述 | 一句话说明用途 | "发起一笔跨境支付请求" |
| 请求参数 | 名称、类型、必填、约束、说明 | amount: number, required, >0, 支付金额（精确到分） |
| 响应结构 | 状态码、字段、类型、说明 | 200: { orderId: string, status: "PENDING" \| "PROCESSING" } |
| 错误码 | 业务错误码及含义 | 4001: 余额不足 |
| 示例 | 完整请求/响应示例 | 包含真实格式的JSON |
| 变更历史 | 版本、日期、变更内容 | v1.2 (2024-03-15): 新增 currency 字段 |
推荐使用OpenAPI 3.0+标准：
| 策略 | 适用场景 | 示例 |
|---|---|---|
| URL版本 | 大规模变更 | /api/v1/... → /api/v2/... |
| Header版本 | 增量更新 | Accept: application/vnd.api+json;version=2 |
| 兼容性原则 | 所有场景 | 新增字段（OK）、删除字段（需发新版本）、修改语义（禁止） |
| 层次 | 位置 | 内容 | 频率 |
|---|---|---|---|
| 文件头 | 文件顶部 | 模块职责、作者、创建日期 | 每个文件 |
| 类/接口 | 声明前 | 设计意图、使用场景、线程安全 | 每个公共类 |
| 方法 | 签名前 | 功能、参数、返回值、异常、示例 | 公共方法 |
| 代码块 | 逻辑段内 | "为什么"而非"做什么" | 复杂逻辑 |
| 行内 | 行尾 | 魔法数字、临时方案、待办 | 必要时 |
// ❌ 坏注释：复述代码
// 将count加1
count++;
// ✅ 好注释：解释原因
// 补偿因并发冲突而丢失的计数，见 issue #2847
count++;
// ❌ 坏注释：过时信息
// 返回用户列表（最多50条）—— 实际已改为分页
// ✅ 好注释：指向决策依据
// 分页大小100基于性能测试，见 docs/perf-test-2024q1.md
private static final int PAGE_SIZE = 100;
// TODO(hugogu, 2024-06-15): 接入新的风控规则引擎，依赖风控团队API文档
// FIXME: 临时绕过缓存一致性问题，等分布式锁方案上线后移除
// HACK: 兼容旧版客户端的畸形请求，v3.0发布后删除
格式：// TODO(负责人, 截止日期): 具体行动
必须包含：
结构化的故障响应指南：
## 告警名称：PaymentTimeoutRateHigh
### 现象
支付接口超时率 > 5%
### 影响范围
- 用户：新支付请求可能失败
- 系统：不影响已处理中的订单
### 排查步骤
1. 检查上游网络延迟：`curl -w "%{time_total}" ...`
2. 检查数据库连接池使用率
3. 检查下游核心银行通道状态
### 应急措施
- 若通道故障：切换至备用通道（见 config/channels.yml）
- 若容量不足：触发扩容流程（见 runbook/scale-up.md）
### 事后复盘模板
- 故障时间线
- 根因分析（5 Whys）
- 改进措施及Owner
在提交或发布文档前，按以下清单自查：
| 场景 | 工具 | 说明 |
|---|---|---|
| 知识库 | Wiki.js / Notion / Confluence | 团队知识沉淀 |
| API文档 | OpenAPI + Swagger UI | 代码即文档 |
| 架构图 | PlantUML / Draw.io / Mermaid | 版本可控的图表 |
| 代码文档 | Javadoc / godoc / rustdoc | 自动生成 |
| 协作编辑 | Markdown + Git | 版本控制、Code Review |
编写 → 自测（清单检查） → 同伴Review → 发布 → 定期Review（季度）
Review关注点：
| 原则 | 实践 |
|---|---|
| 读者优先 | 每段文字都问自己：读者现在需要什么信息？ |
| 具体胜过抽象 | 用示例、数据、场景代替泛泛而谈 |
| 可视化 | 一图胜千言，复杂流程必须配图 |
| 可验证 | 文档中的命令、配置、代码都能实际运行 |
| 持续迭代 | 文档是活的，随系统和认知一起演进 |
| 就近原则 | 信息放在需要它的地方，而非集中存放 |
本文档最后更新：2026-04-29。如有建议或发现过时内容，请通过团队渠道反馈。