文档在软件团队里有一种很矛盾的地位：所有人都知道它重要，但几乎没有人觉得自己真的有时间把它写好。
于是，文档往往不是完全没有，而是总差一点。它记录了昨天，却跟不上今天；熟悉系统的人看得懂，新接手的人却未必能靠它独立判断。
问题通常不在于团队不重视文档，而在于文档每天都在和更紧急的事情竞争。
今天总有更急的事情
生产问题、客户反馈、法规期限、即将上线的版本，这些事情都有人在等，也都有看得见的后果。 文档通常没有。
所以团队每天都会做出一个完全合理的决定：先把眼前的问题解决，之后再补记录。 真正的问题是，“之后”很容易被下一件急事继续推走。
知识负责人在场时，直接问最快
如果最了解这块业务的人就在旁边，直接问他，通常比自己读文档更快。
答案可能三十秒就有，而找到正确页面、判断内容有没有过期，再把上下文拼起来，可能需要更久。 在交付压力下，选择很自然：问清楚，继续做。
没有人正式决定不写文档。团队只是选择了当天成本最低的办法。时间久了，那位知识负责人本人就变成了最可靠、也最方便访问的“文档”。
成本没有消失，只是被推迟了
功能照常上线，问题也顺利解决，短期内看不出损失。
直到有人休假、换组、离职，或者新成员需要接手。那段只存在于对话里的解释突然不在场了。
团队只能重新翻工单、读代码、查数据结构，再从零拼出同一套理解。
原本没有花在记录上的时间，并没有真的省下来，只是变成了未来更昂贵的重建成本。
文档真正缺的，是合适的时机
很多团队把文档安排在实现之后：功能完成，再补说明。
但实现结束的那一刻，往往正是注意力转向下一件事的时候。新的任务已经排队，新的客户问题也已经出现。
把文档放在最后，等于让它去和所有下一步工作竞争。它几乎注定会输。
组织不是突然失去知识的
知识通常是一点点流失的：一个没有记录的决定，一场没有留下结论的会议，一个没人解释的架构假设。
单独看，每一次都很小。累积起来，产品却会一年比一年难理解。
这不完全是技术债，更像知识债。组织并非从未拥有答案，只是把恢复答案的成本留给了以后。
最值得记录的是判断依据
文档不需要复述每一次讨论。真正难以从代码和最终结果中还原的，是为什么选这个方案、哪些选择被放弃，以及这个决定依赖什么前提。 结果会留在系统里，推理过程却常常只留在人脑中。
最适合记录的时刻，不是项目结束后，而是关键决定刚刚做出、上下文还清楚的时候。等得越久，写文档越难，不是因为打字变慢，而是因为记忆已经开始失真。
文档不是交付完成以后才有空做的附加项。它是在今天还记得时，为明天保留判断能力。