软件项目开发全流程 · 第 18 课 · 文档、知识沉淀与沟通
1、"代码能跑就行"是团队的天坑
先看一个熟悉的场景：
团队里最懂支付模块的小王离职了。三个月后线上支付出了 Bug，
没人说得清那段逻辑为什么那么绕、if里那个魔法值0.003是什么。
大家只能对着代码猜，改一处、崩三处。
这就是知识只存在某个人脑子里的代价——巴士因子（Bus Factor）= 1：那个人一旦"上不了班"，项目就瘫一半。
文档与知识沉淀的本质，不是"交作业"，而是把「脑子里的东西」变成「团队能复用的资产」，降低巴士因子。
一句话原则：凡是"说过一次、别人还会再问一次"的东西，就该写下来。
2、文档的四个层次
别一上来就写 100 页。团队文档通常分四层，从"人人都要看"到"少数人才看"：
| 层次 | 代表文档 | 读者 | 更新频率 |
|---|---|---|---|
| 门面 | README | 所有新来的人 | 高 |
| 指南 | CONTRIBUTING、开发环境搭建 | 贡献者 | 中 |
| 设计 | 架构文档、ADR、设计稿 | 开发/评审 | 随改动 |
| 规范/记录 | 编码规范、CHANGELOG、会议纪要 | 团队 | 中 |
关键判断：文档写给谁看？ 写给"半年后的自己"和"刚加入的新人"看。想清楚读者，才知道该写多细。
3、README：项目唯一的"门面"
README 是别人打开你仓库看到的第一屏。它决定一个人是"三分钟跑起来"还是"半小时还没搞明白"。
一个好 README 至少回答四个问题：
# 项目名（一句话：它解决什么问题）
## 快速开始
git clone …
pip install -r requirements.txt
python main.py # 最短路径，能跑起来
## 它是怎么工作的
（3~5 行说明 + 一张架构图/目录说明，指向第 9 课设计文档）
## 常用命令
（测试、构建、部署各一条，别让人翻代码找）
## 贡献方式
（指向 CONTRIBUTING.md）检验标准：让一个没接触过项目的人，只照 README 就能把项目跑起来。 做不到，就说明 README 不合格。
4、设计文档与 ADR：记录"为什么"
代码能说明做了什么，却说不清为什么这么做（第 11 课重点）。
- 设计文档（Design Doc）：开工前写，讲清目标、方案、权衡、取舍。写完走评审（呼应第 9 课架构设计）。
- ADR（架构决策记录）：一次决策一篇短文，格式固定——
# ADR-007：用 Postgres 而非 MongoDB 存订单
- 状态：已采纳（2026-03-01）
- 背景：订单需要强事务与多表关联查询……
- 决策：选用 Postgres
- 后果：牺牲部分 schema 灵活性，换来事务与一致性ADR 的价值在于"决策的墓志铭"：一年后有人问"当初为什么不用 XX"，你能指着文档回答，而不是"记不清了"。
设计文档讲一个系统怎么设计的，ADR 讲一个决策为什么这么做的。两者配合，团队的知识才不会随人流失。
5、让文档"活"起来：Docs as Code
文档最容易死在两件事上：没人写、写了会过期。
"文档即代码（Docs as Code）" 是解药——把文档和代码放同一个仓库、用同一套流程：
- Markdown 写作，和代码一起进 Git，改动走 PR 评审。
- 版本同步：代码改了，文档在同一个 PR 里一起改，天然不脱节。
- 可自动检查：链接失效、格式错误可以放进 CI 检查（第 15 课）。
- 就近放置：模块的说明就放在模块目录旁，读代码时顺手就能看到。
防止过期文档的两个纪律：
- 文档跟着代码改——改行为就改文档，同一个 PR。
- 定期"文档体检"——删掉失效的，比留着一堆过期的更安全（错的文档比没有文档更害人）。
6、注释：代码里的"为什么"
注释不是越多越好。好的注释解释"为什么"，坏的注释复述"是什么"：
# ❌ 废话注释：复述代码
i += 1 # i 加一
# ✅ 有价值的注释：解释意图与陷阱
# 微信回调可能重复推送，这里必须幂等，否则会重复扣款（见 ADR-011）
if order.already_paid:
return原则：能用清晰的命名和结构表达的，就不要用注释（呼应第 16 课编码规范）；注释留给业务背景、踩过的坑、不得已的妥协。
7、沟通：异步优先，会议有纪律
文档解决"知识沉淀"，沟通解决"当下对齐"。团队沟通的两种模式：
| 模式 | 适用 | 要求 |
|---|---|---|
| 异步（Issue/PR/文档评论） | 需要留痕、跨时区、非紧急 | 写清楚：背景 + 问题 + 期望 |
| 同步（站会/评审会/语音） | 需要快速碰撞、有争议 | 有纪律：议程 + 纪要 + 行动项 |
好沟通的底层是"替对方省力"：
- 提问题时，先给出背景（不然对方要反问三轮）。
- 用书面表达复杂的方案（呼应第 11 课技术选型清单）。
- 争议先落到文档/Issue 再讨论，避免"群里吵完就散、结论没人记得"。
给会议立规矩（呼应第 17 课敏捷仪式）：
- 有议程才开会，没有议程的会可以不开。
- 有纪要：决议、谁负责、什么时候完成。
- 行动项进 Issue，不要只躺在纪要里。
- 能异步解决的就别开会——会议是同步沟通里最贵的一种。
8、常见坑
| 坑 | 后果 | 应对 |
|---|---|---|
| 只写代码不写文档 | 巴士因子=1，人走项目瘫 | README + ADR 起步，从"为什么"写起 |
| 文档和代码分家 | 文档迅速过期，没人信 | Docs as Code，同一 PR 一起改 |
| 追求大而全的大部头 | 写完就没人看、没人维护 | 短小、就近、按需写，先写 README |
| 会议没有纪要 | 开完就忘，结论反复 | 每次会产出纪要 + 行动项进 Issue |
| 堆一堆过期/wiki 僵尸页 | 新人被错误信息误导 | 定期体检，删过期比留着强 |
| 群里提问不给背景 | 来回追问，效率极低 | 背景 + 问题 + 期望三件套 |
9、动手实验 🎯
任务：给你的项目补上"知识骨架"。
- 重写一份 README：包含一句话定位、快速开始（能真的跑起来）、目录说明、常用命令。让同学照着跑一遍。
- 写一篇 ADR：挑你项目里一个真实的技术选择（语言/数据库/框架），按"背景-决策-后果"格式记录下来。
- 建 CONTRIBUTING.md：写清如何提 Issue、如何建分支、提交信息规范（呼应第 12 课）、如何发 PR。
- 在项目里挑 3 处最"绕"的代码，补上解释"为什么"的注释；同时删掉 3 处废话注释。
- 维护一份 CHANGELOG：把最近几次改动按"新增/修复/变更"记录（和第 24 课版本号呼应）。
- 开一次 10 分钟站会：定议程、记纪要、把行动项提成 Issue，体会"有纪律的会议"长什么样。
- 写下你项目的免费巴士因子检查：如果核心成员明天离职，哪些知识会丢？列 3 条，补成文档。
做完这步，第三阶段就完整了：从 Git 到协作平台、从 CI 到编码质量、从敏捷到文档沟通——你已经拥有了团队协作的全部基础设施。接下来进入第四阶段：测试与质量。
10、今天你带走的三句话
- 文档是团队资产：把"脑子里的东西"写下来，降低巴士因子；凡是被问过两次的，就该沉淀。
- Docs as Code：文档和代码同仓、同 PR、同评审，才能不过期；错的文档比没有文档更害人。
- 沟通要替对方省力：异步写清楚（背景+问题+期望），同步有纪律（议程+纪要+行动项进 Issue）。
下一阶段进入测试与质量（第 19~23 课）——先认识测试金字塔，回答"测试到底该怎么分层、各投多少"。