技术文档是团队协作、知识传承和系统演进的基石。高质量的文档不仅能降低沟通成本,还能在人员变动时保护组织的知识资产。本文档定义了技术文档的分类体系、编写原则和具体规范,适用于需求文档、设计文档、API文档、操作手册等各类技术文档的编写。
核心原则:文档的价值不在于篇幅,而在于消除歧义、记录决策、加速上手。写文档的成本远低于因误解而返工的成本。
根据多个行业调查,技术文档的投资回报率(ROI)非常显著:
| 投入方面 | 未建立文档规范的团队 | 建立文档规范的团队 | 差异倍数 |
|---|---|---|---|
| 新人上手时间 | 4-8周 | 1-3周 | 2-4x |
| 接口对接沟通轮次 | 5-8轮 | 1-3轮 | 2-5x |
| 系统变更引入的回归缺陷 | 15-25% | 5-10% | 2-3x |
| 故障恢复平均时长(MTTR) | 2-6小时 | 30分钟-2小时 | 2-4x |
| 跨团队沟通占开发时间 | 30-50% | 15-25% | 2x |
真实案例:某中型互联网公司在推行文档规范一年后,新人上手时间从平均6周降至2.5周,跨团队接口对接的返工率从34%降至12%,仅此两项每年节省约1200个工时。
文档不是免费的,需要权衡成本与收益:
| 成本类型 | 说明 | 量化参考 |
|---|---|---|
| 编写时间 | 撰写和维护文档的时间投入 | 设计文档:约开发工时的10-15% |
| 维护成本 | 随系统变更而更新 | 每季度约原编写量的20-30% |
| 阅读成本 | 过度文档导致信息过载 | 超过20页的大型文档,有效阅读率<40% |
| 过时风险 | 过期文档比没有文档更危险 | 过时率>30% 的文档应标注 DEPRECATED |
决策原则:当文档的"编写+维护成本" < "因没有文档而产生的沟通+返工成本"时,文档是值得的。经验法则——影响覆盖超过3个团队或生命周期超过6个月的系统,必须配备完整文档。
技术文档按用途和受众可分为以下几类:
| 文档类型 | 核心目的 | 主要受众 | 典型生命周期 | 建议篇幅 |
|---|---|---|---|---|
| 需求文档 | 明确业务目标和验收标准 | 产品经理、开发、测试 | 随需求变更迭代 | 2-5页 |
| 设计文档 | 记录技术决策和架构方案 | 开发团队、架构师 | 随架构演进更新 | 5-15页 |
| API文档 | 定义接口契约和使用方式 | 前后端开发、外部接入方 | 随接口版本更新 | 自动生成+补充 |
| 操作手册 | 指导部署、运维和故障处理 | 运维、SRE、开发人员 | 随环境变化更新 | 按场景拆分 |
| 事故复盘 | 记录故障根因和改进措施 | 全团队 | 一次性,但需可检索 | 3-5页 |
| 决策记录 | 记录技术选型的思考过程 | 当前及未来团队成员 | 随认知更新补充 | 1-3页 |
原则:文档不是写一次就完事的。每类文档都有其自然生命周期,应建立定期 review 机制,过期文档要及时标注或归档。
在实际工作中,使用以下决策树快速判断需要哪种文档:
开始评估新任务
├── 涉及两个以上团队?
│ ├── 是 → 需求文档 + 设计文档
│ └── 否 → 继续
├── 变更涉及外部 API?
│ ├── 是 → API 文档必须更新
│ └── 否 → 继续
├── 影响部署或运维流程?
│ ├── 是 → 更新操作手册
│ └── 否 → 继续
├── 涉及技术选型或主要架构决策?
│ ├── 是 → 设计文档 + 决策记录
│ └── 否 → 继续
└── 纯内部实现改动(不改变外部行为)?
└── 是 → 代码注释 + 代码 Review 即可
每季度使用以下指标评估文档健康度:
| 指标 | 计算方法 | 健康阈值 | 警示值 |
|---|---|---|---|
| 文档覆盖率 | 核心模块文档数 / 核心模块总数 | > 80% | < 50% |
| 文档新鲜度 | 近6个月更新的文档数 / 总文档数 | > 60% | < 30% |
| 读者满意度 | 季度满意度调查平均分(1-5) | > 4.0 | < 3.0 |
| 查询命中率 | 搜索后5分钟内找到答案的比例 | > 70% | < 40% |
| 独立可执行性 | 按文档操作一次成功的概率 | > 90% | < 60% |
需求文档的核心目标是消除歧义——让开发、测试、产品对"要做什么"和"做到什么程度算完成"达成一致。
| 要素 | 说明 | 示例 |
|---|---|---|
| 背景与目标 | 为什么要做这个需求,解决什么问题 | "当前对账系统每日凌晨2点启动,高峰期延迟导致下游系统阻塞" |
| 范围边界 | 明确包含什么、不包含什么 | "本期仅改造对账任务调度模块,不涉及对账算法本身" |
| 验收标准 | 可验证的完成定义 | "调度延迟从平均15分钟降至2分钟内" |
| 依赖关系 | 上下游依赖和外部约束 | "依赖消息队列升级至v3.2,预计下周完成" |
| 风险与回滚 | 已知风险和应对预案 | "若灰度期间错误率>0.1%,自动回滚至上一版本" |
验收标准的编写推荐使用 Given-When-Then(给定-当-则)格式,这是行为驱动开发(BDD)的核心实践:
场景:用户主动取消订单
给定:用户已登录且有1个状态为"待支付"的订单
当:用户在订单详情页点击"取消订单"
则:订单状态变更为"已取消"
且:库存数量恢复
且:系统向用户发送取消确认通知
验收标准的量化分级:
| 级别 | 描述 | 示例 |
|---|---|---|
| P0 | 不满足则无法上线 | 支付成功必须返回 orderId |
| P1 | 不满足则影响核心体验 | 订单查询响应时间 < 1s |
| P2 | 不满足但可后续迭代 | 支持批量取消订单 |
反模式示例:
# ❌ 错误:过于笼统,无法验证
场景:订单系统性能良好
给定:有1000个并发用户
当:同时提交订单
则:系统应该很快
# ✅ 正确:可量化的验收标准
场景:订单系统高并发处理
给定:有1000个并发用户同时提交订单
当:所有请求在30秒内完成
则:P99响应时间 < 500ms
且:成功率 > 99.5%
且:无数据一致性问题
对于敏捷团队,推荐采用改进版用户故事格式:
作为 [角色]
我希望 [功能描述]
以便 [业务价值]
验收标准:
1. [可验证的条件1]
2. [可验证的条件2]
约束条件:
- [技术约束/业务约束]
- [合规要求]
容易被忽视但至关重要的非功能性需求。以下是完整的NFR检查清单:
| 维度 | 问题示例 | 量化标准示例 |
|---|---|---|
| 吞吐量 | 系统需要支持多少QPS/TPS? | "单集群支持5000 QPS,峰值弹性至8000 QPS" |
| 延迟 | 接口响应时间要求? | P50 < 100ms, P99 < 500ms, P999 < 2s |
| 并发 | 同时在线用户数? | "支持20000并发连接,在线用户50万" |
| 数据量 | 数据增长预估与存储需求? | "日增日志100GB,保留30天,总量3TB" |
SLA目标:99.9%(月停机不超过43分钟)
├── 单点故障:要求消除所有单点
├── 故障切换:主备切换 < 30秒
├── 维护窗口:每月第一个周六 02:00-04:00
└── 数据持久性:99.9999999%(11个9)
设计文档用于对复杂问题与解决方案形成共识,以更高的前期投入为代价,提高交付结果的确定性。设计文档还能为整个团队和公司提供相对完善的整体视图。
设计文档的重点是描述权衡取舍的点,而非开发手册或介绍。以下情况不需要专门的设计文档:
参考:Google的设计文档实践指出,设计文档应该回答"为什么"而非"怎么做"[1]。
1. 背景与目标(1页)
- 要解决什么问题
- 不解决什么问题(范围边界)
2. 现状分析(1-2页)
- 当前系统架构图
- 痛点和数据支撑
3. 方案对比(核心章节)
- 方案A、B、C的概述
- 各方案的优劣对比矩阵
- 最终选择及理由
4. 详细设计(2-5页)
- 架构图(组件、数据流)
- 关键接口定义
- 数据模型变更
5. 风险与应对(1页)
- 技术风险
- 业务风险
- 回滚方案
6. 实施计划(1页)
- 里程碑
- 依赖项
- 验收标准
以一个具体的消息队列选型为例,展示方案对比矩阵的写法:
| 评估维度 | RabbitMQ | Apache Kafka | Pulsar | 权重 |
|---|---|---|---|---|
| 吞吐量 | 10K msg/s | 100K+ msg/s | 100K+ msg/s | 30% |
| 消息持久化 | 支持 | 强(默认持久化) | 强(分层存储) | 10% |
| 消息顺序保证 | 单队列有序 | 分区内有序 | 分区内有序 | 15% |
| 运维复杂度 | 较低 | 中等 | 较高 | 15% |
| 延迟 | 微秒级 | 毫秒级 | 毫秒级 | 10% |
| 社区成熟度 | 极高 | 极高 | 中等 | 10% |
| 团队熟悉度 | 有3年经验 | 熟悉 | 无经验 | 10% |
加权评分结果:
决策:选择Kafka,原因是:
量化对比矩阵让决策过程透明化,即使未来条件变化(如延迟要求变得严格),也能清晰知道需要换方案。
每一个关键设计决策都应当记录在案:
# ADR-001: 采用事件驱动架构替代REST API同步调用
## 状态
✅ 已采纳(2026-01-15)
## 背景
订单创建后需要通知6个下游系统(库存、物流、财务、推荐、CRM、BI),同步调用导致核心链路不稳定。
## 决策
采用Kafka事件总线,订单服务发布OrderCreated事件,下游自主消费。
## 方案对比
| 维度 | 同步调用 | 事件驱动 | 消息队列+回调 |
|------|---------|---------|-------------|
| 订单主链路可用性 | 99.8% | 99.99% | 99.9% |
| 下游新增成本 | 改主链路代码 | 新增消费者即可 | 改主链路+MQ配置 |
| 问题排查难度 | 追踪调用链 | 需事件追踪工具 | 中等 |
| 数据一致性保证 | 直接(2PC) | 最终一致性 | 最终一致性 |
## 后果
- ✅ 订单主链路可用性提升至99.99%
- ✅ 新下游系统接入时间从2周降至2天
- ⚠️ 需要引入事件追踪工具(已选EventCatalog)
- ⚠️ 团队需要学习事件驱动开发模式
- ⚠️ 需处理事件的顺序性和幂等性
## 替代方案
- 异步RPC + 回调:被否决,复杂度相当但扩展性不如事件驱动
C4模型层级示意:
Level 1: System Context(系统上下文)
[用户] ──→ [订单系统] ──→ [支付系统]
│ │
└──────── [物流系统] ←─────┘
Level 2: Container(容器/服务)
[Web App] ──→ [订单API服务] ──→ [数据库(MySQL)]
│ │
│ [消息队列(Kafka)]
│ │
└── [通知服务] ←─┘
Level 3: Component(组件)
[订单API服务]
├── OrderController → 接收外部请求
├── OrderService → 核心业务逻辑
├── PaymentClient → 调用支付系统
└── EventPublisher → 发送领域事件至Kafka
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 字段 |
以"创建支付订单"接口为例,展示一份合格的API文档应包含的内容:
## POST /api/v1/payments
创建一笔支付订单。
### 请求头
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Content-Type | string | 是 | `application/json` |
| Authorization | string | 是 | `Bearer {token}` |
### 请求体
```json
{
"orderId": "ORD-20260301-0001",
"amount": 299900,
"currency": "CNY",
"paymentMethod": "alipay",
"callbackUrl": "https://merchant.com/callback",
"metadata": {
"source": "ios_app",
"campaignId": "SPRING2026"
}
}
| 字段 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|
| orderId | string | 是 | 长度32,字母数字+连字符 | 商户订单号 |
| amount | int | 是 | > 0,单位为分 | 支付金额 |
| currency | string | 是 | ISO 4217 | 币种代码 |
| paymentMethod | string | 是 | enum: alipay/wechat/card | 支付方式 |
| callbackUrl | string | 否 | 合法URL,HTTPS | 支付结果通知地址 |
| metadata | object | 否 | 最大5个key | 补充信息 |
成功响应(200)
{
"code": 0,
"message": "success",
"data": {
"paymentId": "PAY-20260301-89012",
"status": "PENDING",
"redirectUrl": "https://pay.example.com/pay/PAY-20260301-89012",
"expiresAt": "2026-03-01T01:15:00Z"
}
}
错误响应(4xx/5xx)
| HTTP状态码 | errorCode | message | 说明 |
|---|---|---|---|
| 400 | INVALID_PARAM | "orderId already exists" | 订单号重复 |
| 400 | INVALID_PARAM | "amount must be positive" | 金额不合法 |
| 401 | UNAUTHORIZED | "Invalid or expired token" | 鉴权失败 |
| 403 | FORBIDDEN | "Merchant account frozen" | 商户账户被冻结 |
| 429 | RATE_LIMITED | "Too many requests" | 超出API限频 |
| 500 | INTERNAL_ERROR | "Internal server error" | 服务端异常 |
| 维度 | 限制 | 超出后行为 |
|---|---|---|
| 商户级别 | 100 req/s | 429错误,1分钟后恢复 |
| 用户级别 | 10 req/s | 429错误,30秒后恢复 |
| IP级别 | 1000 req/s | 429错误,5分钟后恢复 |
每个orderId在24小时内只能创建一次支付请求。重复请求返回相同的paymentId。
支付状态变更时,通过callbackUrl以POST方式发送通知:
{
"paymentId": "PAY-20260301-89012",
"orderId": "ORD-20260301-0001",
"status": "SUCCESS",
"amount": 299900,
"paidAt": "2026-03-01T01:05:00Z"
}
通知重试策略:最多重试3次,间隔5分钟/15分钟/30分钟。
### 5.3 OpenAPI/Swagger规范
推荐使用OpenAPI 3.0+标准:
- 使用工具自动生成(如SpringDoc、Swaggo)
- 注释即文档,代码与文档同步
- 支持在线调试和Mock
- 可导出为PDF/HTML供外部接入方使用
**最小OpenAPI 3.0示例**:
```yaml
openapi: 3.0.0
info:
title: 支付服务 API
version: 1.2.0
description: 跨境支付服务接口定义
paths:
/api/v1/payments:
post:
summary: 创建支付订单
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
responses:
'200':
description: 成功创建订单
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
components:
schemas:
CreatePaymentRequest:
type: object
required: [orderId, amount, currency, paymentMethod]
properties:
orderId:
type: string
description: 商户订单号
amount:
type: integer
description: 金额(分)
currency:
type: string
enum: [CNY, USD, EUR]
| 策略 | 适用场景 | 示例 | 优缺点 |
|---|---|---|---|
| URL版本 | 大规模不兼容变更 | /api/v1/... → /api/v2/... |
清晰但URL膨胀 |
| Header版本 | 增量兼容更新 | Accept: application/vnd.api+json;version=2 |
干净但有发现成本 |
| Query版本 | 快速迭代 | /api/payments?version=2 |
简单但容易缓存问题 |
兼容性原则:
版本迁移策略:
v1 → v1+v2共存(6个月,逐步迁移)→ v1弃用(标注Deprecated,3个月)→ v1下线
维护新旧版本的并行技术方案:
| 方案 | 成本 | 灵活性 | 推荐场景 |
|---|---|---|---|
| 网关层路由 | 低 | 中 | 简单路径/Header匹配 |
| 适配器模式 | 中 | 高 | 业务逻辑差异大 |
| 独立部署 | 高 | 极高 | 彻底重构 |
| 层次 | 位置 | 内容 | 频率 |
|---|---|---|---|
| 文件头 | 文件顶部 | 模块职责、作者、创建日期 | 每个文件 |
| 类/接口 | 声明前 | 设计意图、使用场景、线程安全 | 每个公共类 |
| 方法 | 签名前 | 功能、参数、返回值、异常、示例 | 公共方法 |
| 代码块 | 逻辑段内 | "为什么"而非"做什么" | 复杂逻辑 |
| 行内 | 行尾 | 魔法数字、临时方案、待办 | 必要时 |
// ❌ 坏注释:复述代码
// 将count加1
count++;
// ✅ 好注释:解释原因
// 补偿因并发冲突而丢失的计数,见 issue #2847
count++;
// ❌ 坏注释:过时信息
// 返回用户列表(最多50条)—— 实际已改为分页
// ✅ 好注释:指向决策依据
// 分页大小100基于性能测试,见 docs/perf-test-2024q1.md
private static final int PAGE_SIZE = 100;
上下文场景:缓存逻辑
// ❌ 坏注释:只是描述了代码在做的事情
// 从redis获取数据,如果没有则从数据库加载
const data = await redis.get(key);
if (!data) {
data = await db.load(id);
await redis.set(key, data);
}
// ✅ 好注释:解释了为什么和权衡
// 采用旁路缓存(Read-Aside)策略而非穿透式缓存:
// 1. 数据更新频率低(< 1次/小时)
// 2. 一致性强于缓存穿透方案
// 3. 需要容忍最多5秒的陈旧数据
// Redis TTL设为5秒而非更久,因为上游支付状态变更需尽快反映
const CACHE_TTL_SECONDS = 5;
const data = await cache.get(key);
if (!data) {
data = await db.load(id);
await cache.set(key, data, CACHE_TTL_SECONDS);
}
上下文场景:边界条件处理
# ❌ 坏注释:只说明了类型转换
# 将字符串转为整数
count = int(raw_count)
# ✅ 好注释:解释了边界条件和容错策略
# 解析外部API返回的count字段,该字段在空值时返回"null"字符串
# 而非null值或N/A,这是已知的v2.3 bug(见外部厂商issue #4521)
# 容错策略:无法解析时默认0,保证不阻塞主流程
try:
count = int(raw_count)
except (ValueError, TypeError):
count = 0
logger.warning(f"无法解析count字段: {raw_count}, 使用默认值0")
// TODO(hugogu, 2024-06-15): 接入新的风控规则引擎,依赖风控团队API文档
// FIXME: 临时绕过缓存一致性问题,等分布式锁方案上线后移除
// HACK: 兼容旧版客户端的畸形请求,v3.0发布后删除
格式:// TODO(负责人, 截止日期): 具体行动
推荐的TODO标签体系:
| 标签 | 含义 | 预期处理时间 |
|---|---|---|
TODO |
计划做但尚未实施 | 持续跟踪,按计划处理 |
FIXME |
已知缺陷或问题 | 尽快修复(1-2个迭代内) |
HACK |
临时绕过方案 | 标记永不过期或设定截止日期 |
XXX |
强烈建议修改的危险代码 | 立即处理 |
OPTIMIZE |
性能优化点 | 有性能指标时处理 |
REVIEW |
需要团队Review的代码 | 下次Code Review |
必须包含:
部署手册模板示例:
# [服务名称] 部署手册
## 环境要求
| 资源 | 最低要求 | 推荐 |
|------|---------|------|
| CPU | 4核 | 8核 |
| 内存 | 8GB | 16GB |
| 磁盘 | 50GB SSD | 100GB SSD |
| OS | Ubuntu 20.04+ / CentOS 7+ | Ubuntu 22.04 |
| Java | JDK 17+ | JDK 21 LTS |
| MySQL | 8.0+ | 8.4 LTS |
## 配置项说明
| 配置键 | 默认值 | 说明 | 修改建议 |
|--------|-------|------|---------|
| `server.port` | 8080 | HTTP服务端口 | 不修改 |
| `spring.datasource.url` | — | 数据库连接串 | 按环境配置 |
| `app.rate.limit` | 100 | API限频(次/秒) | 生产环境:1000 |
| `logging.level.root` | INFO | 日志级别 | 排查问题时改为DEBUG |
## 部署步骤
```bash
# 1. 拉取最新版本
git checkout tags/v2.1.0
# 2. 构建
./gradlew build -x test
# 3. 检查配置文件
diff config/application-prod.yml expected-config.yml
# 4. 启动
nohup java -jar build/libs/payment-service-2.1.0.jar \
--spring.profiles.active=prod \
> /var/log/payment-service/stdout.log 2>&1 &
# 5. 验证
curl -s http://localhost:8080/actuator/health | jq .status
# 预期输出: {"status":"UP"}
# 6. 检查日志无异常
tail -50 /var/log/payment-service/application.log
# 1. 停止当前版本
kill $(cat /var/run/payment-service.pid)
# 2. 启动上一个版本
nohup java -jar /opt/payment-service/releases/v2.0.9/payment-service-2.0.9.jar \
> /var/log/payment-service/stdout.log 2>&1 &
# 3. 验证回滚成功
curl -s http://localhost:8080/actuator/info | grep version
# 预期输出: "version": "2.0.9"
### 7.2 故障处理手册(Runbook)
结构化的故障响应指南:
支付接口超时率 > 5%
curl -w "%{time_total}" ...
**完整的Runbook示例**:
```markdown
# Runbook: 数据库连接池耗尽
## 告警规则
MySQL连接使用率 > 80%,持续5分钟后触发P0告警
## 影响评估
- 100% 读数据库的接口不可用
- 写数据库的接口堆积请求,可能导致全站雪崩
- 预估恢复时间:10-30分钟
## 紧急止血(5分钟内完成)
### Step 1: 确认告警真实性
```sql
-- 检查当前连接数
SHOW STATUS LIKE 'Threads_connected';
-- 检查最大连接数配置
SHOW VARIABLES LIKE 'max_connections';
-- 临时增加最大连接数(重启后失效)
SET GLOBAL max_connections = 500;
-- 重启应用使新连接池大小生效
kubectl rollout restart deployment/payment-service
-- 查看哪些连接在长时间Sleep
SHOW PROCESSLIST;
-- 找出执行时间最长的查询
SELECT * FROM information_schema.processlist
WHERE time > 300 ORDER BY time DESC;
connection.close() 或 try-with-resourcesspring.datasource.hikari.leak-detection-threshold=60000
### 7.3 日志规范
- **结构化日志**:JSON格式,便于检索和分析
- **必填字段**:timestamp、level、service、trace_id、message
- **敏感信息**:禁止记录密码、token、完整卡号(可脱敏后记录后4位)
- **日志级别使用**:
- ERROR:需要立即处理的异常
- WARN:需要关注但不一定立即处理
- INFO:正常业务流程节点
- DEBUG:开发排查用,生产环境通常关闭
**结构化日志示例(JSON格式)**:
```json
{
"timestamp": "2026-03-01T10:30:00.123+08:00",
"level": "INFO",
"service": "payment-service",
"trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"user_id": "usr_abc123",
"message": "支付订单创建成功",
"extra": {
"order_id": "ORD-20260301-0001",
"amount": 299900,
"currency": "CNY",
"duration_ms": 145
}
}
不同场景的日志最佳实践:
| 场景 | 建议级别 | 应记录的内容 | 不应记录的内容 |
|---|---|---|---|
| 用户注册 | INFO | user_id, email(部分脱敏) | 密码、完整手机号 |
| API限频触发 | WARN | 用户IP、请求路径、触发时间 | Token、Session |
| 数据库超时 | ERROR | SQL(参数化)、超时时长 | 数据库密码 |
| 第三方调用失败 | ERROR | 接口名、请求ID、HTTP状态码 | API Key、Token |
| 业务规则校验失败 | WARN | 校验失败的字段和值 | 用户隐私数据 |
在提交或发布文档前,按以下清单自查:
| 检查项 | 如果不满足 | 典型的修改方法 |
|---|---|---|
| 每个段落不超过5句话 | 读者跳过长段落 | 拆分为2-3段的短段落 |
| 每个句子不超过30个字 | 读者失去上下文 | 拆分长句,使用列表 |
| 技术名词首次出现时有定义 | 读者困惑 | 参考其他文档(如"幂等性"首次出现时标注定义链接) |
| 每个代码块有语言标注 | 无语法高亮 | 在首行标注语言(如python) |
| 列表项不超过7项 | 读者记不住 | 拆分列表或使用表格 |
| 场景 | 工具 | 说明 |
|---|---|---|
| 知识库 | Wiki.js / Notion / Confluence | 团队知识沉淀 |
| API文档 | OpenAPI + Swagger UI | 代码即文档 |
| 架构图 | PlantUML / Draw.io / Mermaid | 版本可控的图表 |
| 代码文档 | Javadoc / godoc / rustdoc | 自动生成 |
| 协作编辑 | Markdown + Git | 版本控制、Code Review |
| 工具 | 学习成本 | 维护成本 | 协作能力 | 版本控制 | 自动化 |
|---|---|---|---|---|---|
| Wiki.js | ⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| Markdown + Git | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Confluence | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| Notion | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐ | ⭐⭐ |
推荐方案:面向全团队的百科式文档 → Wiki.js;面向开发者的技术规范/API文档 → Markdown + Git;面向产品/运营的协作文档 → Notion。
编写 → 自测(清单检查) → 同伴Review → 发布 → 定期Review(季度)
Review关注点:
文档Review检查单:
| 检查维度 | Reviewer职责 | 示例问题 |
|---|---|---|
| 技术准确性 | 领域专家(开发/架构师) | "这个配置参数在2.0版本已废弃,说法不准确" |
| 表达清晰度 | 非领域读者(新人/PM) | "第三段的引用链式图我看不懂" |
| 完整性 | 文档经验者(Tech Lead) | "没有提到回滚方案" |
| 可操作性 | 运维/QA | "Step 1的命令路径不对,我无法复现" |
在PR模板中嵌入文档要求:
## PR 提交检查清单
- [ ] 代码修改是否影响外部API?(是/否,若是请更新API文档)
- [ ] 是否引入新的配置项?(是/否,若是请更新配置说明文档)
- [ ] 是否修改部署流程?(是/否,若是请更新运维手册)
- [ ] 是否有架构变更?(是/否,若是请更新架构图)
- [ ] 所有新增功能是否对应新增测试用例?
不同类型的文档有不同的最佳更新时间:
| 文档类型 | 建议Review周期 | 典型"保质期" | 过期处理方式 |
|---|---|---|---|
| 决策记录(ADR) | 6个月 | 1-3年 | 标记为"已废弃/已重新评估" |
| 设计文档 | 每季度 | 6个月-1年 | 归档至"历史版本" |
| API文档 | 每次版本发布 | 与API版本一致 | 随接口下线而删除 |
| 操作手册 | 每次环境变更 | 3-6个月 | 替换为新版,保留ChangeLog |
| 需求文档 | 每次迭代后 | 1个迭代周期 | 归档至项目记录 |
| 团队规范 | 每半年 | 6个月-1年 | 用新版本完全替换 |
文档创建 → 活跃维护 → 检出过期 →审核 → 更新 → 确认无价值 → 归档
│ │
└── 更新 ────────────────┘
未更新,已过时 ──→ 标注 OBSOLETE ──→ 归档(保留6个月后删除)
归档格式:
---
status: ARCHIVED
last_valid: 2025-12-01
archived_at: 2026-03-01
replaced_by: /zh/tech/guidance/service-arch-v2
reason: 架构从微服务迁移至Serverless,原设计已不适用
---
# v1设计文档(已归档 — 仅供参考)
复杂度-文档深度映射:
| 系统复杂度 | 影响团队数 | 建议文档深度 | 例子 |
|---|---|---|---|
| 低(1人月内完成) | 1-2个 | 代码注释+简短的README | 内部工具脚本 |
| 中(3-6人月) | 2-3个 | 完整设计文档+API文档 | 新API服务 |
| 高(1年+) | 3个以上 | 完整设计+ADR+运维手册+架构图 | 核心业务平台 |
| 极高(跨部门/公司) | 5个以上 | 全部文档类型+培训材料 | 开放平台/支付系统 |
"文档漂移"的量化评估:每季度随机抽取10个文档,检查其内容与代码的匹配度。如果匹配率低于60%,需要启动文档修复计划。
"公交车指数"(Bus Factor)评估:对于每个核心模块,如果唯一知道其内部工作方式的成员因病请假或离职,团队能在多久内恢复运行?如果答案超过1天,则需要改进文档化。
增量文档化策略:
第1天:标题 + 大纲(5分钟)
第2天:核心逻辑段落(15分钟)
第3天:补充例子和边界情况(15分钟)
第4天:增加图表或参考链接(10分钟)
第5天:邀请同事Review(10分钟)
金字塔原理:只要骨架正确,内容的填充随时可以完成。完成一篇"够好"(Good Enough)的文档,远比追求完美但从未发布的文档更有价值。
| 反模式 | 识别标志 | 修正方法 |
|---|---|---|
| 镀金文档 | 文档篇幅超出主题需求的3倍以上 | 按"最小必要信息"原则删减 |
| 僵尸文档 | 最后更新日期是1年以前 | 标注Deprecated或更新 |
| 回音室文档 | 多人反复重写同一部分 | 锁定争议部分,引用原始ADR |
| 清单文档 | 只有提纲没有内容 | 逐个提纲填充3句话以上的内容 |
| 抽象废话 | 全是原则没有例子 | 每个原则配1-2个实际案例 |
| 信息孤岛 | 没有交叉引用其他文档 | 添加相关文档的双向链接 |
| 原则 | 实践 |
|---|---|
| 读者优先 | 每段文字都问自己:读者现在需要什么信息? |
| 具体胜过抽象 | 用示例、数据、场景代替泛泛而谈 |
| 可视化 | 一图胜千言,复杂流程必须配图 |
| 可验证 | 文档中的命令、配置、代码都能实际运行 |
| 持续迭代 | 文档是活的,随系统和认知一起演进 |
| 就近原则 | 信息放在需要它的地方,而非集中存放 |
| 成本意识 | 文档的成本(编写+维护)应始终小于无文档的成本(沟通+返工) |
| 可度量 | 用覆盖率、新鲜度、读者满意度评估文档健康度 |
| 先骨架后填充 | 先建立完整的大纲结构,再逐步填充内容 |
| 反馈闭环 | 每篇文档都应提供反馈渠道,持续改进 |
| 你遇到了什么问题? | 应该怎么做 |
|---|---|
| 团队新人上手慢 | 编写入门指南:开发环境搭建 → 项目结构 → 首个PR流程 |
| 接口对接总是出错 | 建立API文档规范,使用OpenAPI + Swagger |
| 架构决策"失忆" | 引入ADR,每个关键决策记录Why和Trade-off |
| 线上故障恢复慢 | 编写Runbook,标准化故障响应流程 |
| 文档没人读 | 检查文档是否过时、是否太啰嗦、是否在正确的位置 |
| 写完就没人管了 | 建立定期Review机制,将文档纳入DoD |
本文档最后更新:2026-05-28。如有建议或发现过时内容,请通过团队渠道反馈。