ARTICLE · 1304143
文档是写给未来自己的
文档是写给未来自己的
你肯定干过这事。一个需求上线，代码写得飞起，注释一行没有，交接文档拖到离职前三天才补。补的时候脑子里一片空白，这字段为什么叫这个名字，这个判断为什么这么写，全忘了。最后凑出几百字，自己都看不懂。 我们总觉得文档是给别人看的。写给领导看，显得我做事规范；写给同事看，显得我好交接；写给后来的人看，显得我有格局。 错了。 文档真正读它的人，是三个月后的你自己。 三个月后你接到一个线上 bug，半夜爬起来排查，一路追到那段逻辑。你盯着屏幕，像在看别人写的代码。那时候你才明白，当初省下的那十分钟，现在要花三个小时还。 这不是让你把每件事都写成论文。就三条，能救命。 写"为什么"，别只写"是什么"。这个判断为什么这么下，这个方案为什么没用另一个。过阵子你会忘了当时的纠结，只记得结论，然后就没人能推翻它了。 当场写，别事后补。事后的记忆会自动美化，把当时的犹豫和坑都抹平了。你补出来的文档，是给面子工程看的，不是给未来的自己用的。 写给那个完全失忆的人。假设读的人什么都不知道，一个背景都没有。你就知道该写什么了。 文档这东西，看着是给人看的，其实是给那个会忘记的你留的后路。 明天那个项目，别等它烂在脑子里了。
