技术文档管理规范

# 技术文档管理规范

API文档、架构文档、知识库维护——文档活起来才有价值

# 一、文档最大的问题：写完之后没人再看

你花 2 天写了一篇架构文档，精雕细琢——3 个月后有人打开它，
发现里面描述的系统已经重构了两次，文档过时了。

同样 3 个月后另一个同事问你："这个支付流程到底怎么回事？"
你回他："wiki 上有啊，我写了一篇。"他打开一看——"但这是老架构的文档啊。"

1
2
3
4
5

文档不维护比没有文档更危险。 没有文档，同事知道"我不知道"——他会去问人。过时文档让他以为"我知道了"——直到上线出问题。

# 二、文档的类型——不是所有东西都值得写成文档

值得写的（Doc）：
  □ 架构决策记录（ADR）——"为什么我们选了 Redis 而不是 Memcached"
  □ API 接口文档——结构化、自动生成
  □ Oncall 记录——事故复盘
  □ 新人入职指南——环境搭建流程
  □ 编码规范——团队统一的风格约束

不值得写的：
  □ 会议纪要（除非有决策）——用 Jira/Linear comment 代替
  □ "how-to" 教程类（除非团队独有操作）——网上大把，复制链接更好
  □ 个人笔记——放你自己笔记本里，不要污染团队 wiki

1
2
3
4
5
6
7
8
9
10
11

判断标准：这个文档半年后还有人需要看吗？会 → 写。不会 → 别写，或用更高效的方式传递信息。

# 三、API 文档——能自动生成就不要手写

❌ 手写 API 文档：
  - 改了代码忘了改文档 → 文档和实现不一致
  - 前端看着文档调用，返回的字段和文档不一样 → "文档不对"

✅ 从代码/注释自动生成：
  - Swagger / OpenAPI（Java/Kotlin 生态）
  - apidoc / JSDoc（Node.js 生态）
  - grpc-gateway + protobuf（gRPC 生态）

原理：文档和代码在同一个源。改了代码就改了文档。没法不同步。

1
2
3
4
5
6
7
8
9
10

手写 API 文档的唯一场景：对外公开的 API，需要配示例和说明。但即使这样，字段定义也应该从代码生成后手动补充说明文字。

# 四、文档的存活系统——四层维护机制

# 4.1 ADR——架构决策记录

永远不要只记"最终选了什么"——要记"为什么这么选，以及当时不选的其他方案"。

ADR 模板（一段话就够了）：

# ADR-003：选择 Kafka 代替 RabbitMQ 做订单事件总线

背景：订单系统需要在多个服务间广播状态变更事件。

决策：选用 Kafka。

原因：
  1. 预期消息量会从 1000/s 涨到 50000/s，RabbitMQ 的横向扩展不如 Kafka
  2. 下游需要消息重放能力（回溯历史订单事件），Kafka 的持久化天然支持
  3. 团队已有 Kafka 运维经验

后果：
  优点：吞吐量够未来三年用
  缺点：增加了运维复杂性，PHP 接入 Kafka 需要额外适配层

替代方案：
  - RabbitMQ：开发快但吞吐量上限低，半年后可能需要再次迁移
  - RocketMQ：功能和 Kafka 类似，但社区活跃度和人才池更小
  - 不引入消息队列：当前架构已经快撑不住了，必须改

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

ADR 的价值不是当时写它的那一刻——是一年后你忘了当时怎么想的，它能帮你回忆。

# 4.2 文档的定期巡检

每季度一次文档巡检：

□ 找 3 篇最常被访问的文档——确认内容仍然正确
□ 找 3 篇创建超过 6 个月但从未被打开过的文档——考虑归档或删除
□ 问问 team 新人："入职一个月，最想吐槽文档里的什么？"

文档巡检花 1 小时，省的是团队全年找信息的时间。

1
2
3
4
5
6
7

# 4.3 过时文档的处置

过时文档三种处置：

1. 归档（Archive）：移到 archive 目录，不在主搜索范围内
2. 标记过时：在顶部加一条 "⚠️ 本文档最后更新于 2023-01，可能和当前实现不一致"
3. 更新：如果还有人需要这篇文档，责任人是上次修改对应代码的人

不做的事：直接删。过时文档也是历史记录——记录了我们曾经怎么想的。

1
2
3
4
5
6
7

# 五、知识库——让信息"找得到"

# 5.1 目录结构

工程师 wiki 建议结构：

/engineering
  /architecture        → 架构决策记录（ADR）
  /services            → 每个微服务的文档（API、数据模型、部署信息）
  /oncall              → 事故复盘记录
  /howto               → 团队独有操作指南（环境搭建、发布流程等）
  /standards           → 编码规范、Review 规范、技术选型原则
  /onboarding          → 新人入职指南

1
2
3
4
5
6
7
8
9

# 5.2 搜索比分类重要

你知道信息在哪但找不到 → 分类的问题
你根本不知道这个信息存不存在 → 搜索的问题

确保可搜索：
  □ 标题要包含关键词。不是"XX 系统优化记录"，是"支付系统慢查询优化记录"
  □ 文档内链接——从架构文档链到对应的 ADR，从 oncall 链到修复 PR
  □ 重要文档固定（pin）到 wiki 首页或团队频道

1
2
3
4
5
6
7

# 六、小结

文档管理的三个原则：

1. 少而精     → 不是什么都写。写最重要的那 20%，它覆盖 80% 的需要
2. 和代码同源 → API 文档自动生成；架构决策和代码仓一起存
3. 定期巡检   → 一个季度花 1 小时，保证文档"还活着"

1
2
3
4
5

行动清单：

[ ] 打开 wiki，找一篇你最近写的文档——里面的信息还准确吗？
[ ] 你们团队的 API 文档是手写的还是自动生成的？手写的话——未来三个月能改成自动吗？
[ ] 下一次做技术选型后，写一篇 ADR——只写"因为什么选了这个，不选的其他方案是什么"

#文档

上次更新: 2026/06/15, 14:32:53

← 线上事故响应流程 README→