精华社 · 藏经阁

外观

文档执念：被低估的工程杠杆

约 1229 字

文档执念：被低估的工程杠杆

团队里最不受待见的活：写文档。KPI 不算、 工期不排、「先上线后补」（然后永远不补）。

但我的经验相反：写文档是我回报率最高的习惯， 个人和团队都是。这篇说说为什么，以及怎么写。

一、文档的复利

代码的价值随时间衰减（过时、被重构、被遗忘）， 好文档反而升值：

新人 onboarding：有文档三天上手，没文档一个月还问
线上故障：有 runbook，值班的不慌；没有，半夜打电话
需求沟通：写在文档里的，比「当时说好的」可靠一万倍
知识传承：人走了，文档在 —— 离职交接的救命绳

算笔账：一个 5 人团队，每周花 2 小时写文档， 一个月 40 小时。换来的：新人少问 80 个问题、 事故响应快一半、需求扯皮少三成。这投资回报率， 去哪找。

二、个人层面：写作是最好的思考

写文档对写作者自己的回报（比团队更大）：

  • 逼你想清楚：「这个模块怎么工作」—— 能写明白，才是真明白。写不下去的地方， 就是你理解的黑洞；
  • 建立个人品牌：技术圈混，最后拼的是 「你写的东西有没有人看」—— 本站就是这么一张名片；
  • 一次劳动多次回报：回答别人时贴链接、 教新人时发文档、面试时讲项目 —— 都吃「写过」的老本。

「这个我懂但说不清」= 不懂。 文档是懂的试金石。

三、什么文档真的有人看

不是所有文档都配写。按「看的人数 × 看的频率」排：

必写：
- README（项目的脸，没有 = 不存在）
- 新人上手文档（onboarding，一次写所有人受益）
- 运维手册/runbook（出事时的救命稻草）
- 架构决策记录（ADR：为什么这么设计）

选写：
- API 文档（能用工具生成别手写）
- 代码注释（解释「为什么」不是「是什么」）
- 教程（对外产品向）

别写：
- 没人维护的「设计文档」（写完即过期，成历史文物）
- 照抄代码的注释（代码会变，注释说谎最可恨）

判断标准：三个月后还有人会打开它吗？ 不会，别浪费生命。

四、怎么写（实操）

结构比文采重要

# 标题：说清这是什么
## 快速开始：三行跑起来
## 常见问题：报错 → 解法
## 深入：原理/架构（可选）

「快速开始」放最前 —— 没人有耐心读你的 设计哲学，先让人跑起来。

写给「三个月后的自己」

❌「此模块负责相关业务处理」（废话）
✅「订单模块：处理下单流程。注意：支付回调
   有重试，必须幂等（见 lock 实现）」

「注意」和「为什么」是文档的黄金内容 —— 代码不会说的，才是文档该写的。

和代码同仓库

✅ docs/ 目录，跟代码一起 git 管理，PR 一起 review
❌  wiki 另一个系统，三个月后和代码对不上

文档离代码越近，腐烂得越慢。 改代码的 PR 顺手改文档（哪怕一行），是团队该有的纪律。

五、团队落地：从最小开始

推文档文化，别搞「文档大跃进」：

  1. 先要求 README：每个仓库一个像样的 README （是什么、怎么跑、怎么测）—— 这一条就够起步；
  2. 模板化：常见文档类型给模板（onboarding、 ADR、runbook），填表比写字容易；
  3. PR 带着改：改功能的 PR，附上文档改动 （review 时一起看）；
  4. 定期盘点：季度 review 一次文档， 过时的标记「已过期」或删 —— 烂文档比没文档更毒（它会骗人）；
  5. 认可它：standup 上夸「文档写得好」的人 —— 行为被看见，才会被重复。

六、本站的实践

技术客栈本身就是「文档执念」的产物：

  • 80+ 篇文章，全是「踩过的坑 + 讲透的原理」；
  • 每篇注明环境版本（防过时）；
  • 站内互链成网（知识的地图，不是孤岛）；
  • 投稿流程 本身就是一份「可执行的文档」。

「文档即产品」 —— 本站没 App 没服务， 文档就是交付物。这个认知，是被 WordPress 时代 「啥都得运维」毒打出来的。

小结

文档三本账：团队账（新人/故障/扯皮都变快）、 个人账（逼你想清 + 建名声）、时间账（一次写， 反复用）。写文档的秘诀：写给三个月后的自己、 写「代码不会说的」、跟代码同仓库。 工程师的分工到最后，拼的是「让别人（和未来的自己） 少走弯路」的能力 —— 这就是文档。