人们真的会读的文档

四份文档就够了

入门文件。这是什么、怎么在本地运行、怎么跑测试、有问题问谁。它必须准确——它是每次新人入职都会被检验的那份文档。

架构决策。每个重要决策一页：背景、备选方案、选了什么、为什么。简短并注明日期。

运维。出问题时做什么、怎么部署、怎么回滚。

接口。从代码里生成，这样不会过期。

怎么保持新鲜

让文档活在代码旁边，并在同一个合并请求里更新。放在别处的文档两个月就会过期，更糟的是——它看上去仍然很权威。

不该记录什么

代码本身已经说清楚的东西。描述某一行在做什么的注释是多余的；解释「为什么选了一个不寻常的做法」的注释，价值连城。