写文档ROI 730%：程序员最亏本的习惯

写文档ROI 730%：程序员最亏本的习惯

上周五下午，我写了一个很巧妙的缓存淘汰策略。本地缓存+Redis两级联动，带版本号的失效机制，我自己都觉得挺漂亮。

周一，后端的小王跑来问我：”哥，你那个缓存是怎么回事？我要接一个新接口，不知道该怎么处理缓存。”

我放下手里的活，花了15分钟给他讲了一遍。画了个图，解释了为什么用版本号而不是TTL，怎么处理并发写入的脏数据问题。小王听懂了，走了。

周二，前端的小李来了：”哥，我这边请求有时候拿到旧数据，是不是缓存的问题？”

又是15分钟。

周三，新来的实习生在群里问：”请问缓存策略在哪个文件里？我翻了半天没找到。”

又是15分钟——而且这次我得从”什么是两级缓存”开始讲起。

半年下来，我大概解释了20遍。每次15分钟，总共5个小时。如果当初我花30分钟写个文档，后面19次每次就是一个链接的事。

30分钟 vs 5小时。你告诉我，哪个更浪费时间？

“没时间写文档”是程序员最贵的借口

我知道你在想什么——”我也知道文档好，但我真的没时间啊。”

有意思的是，你永远有时间解释第20遍，但没时间写第1遍。

这就是写文档最反直觉的地方：不写文档才是真正的浪费时间。只不过这个浪费不是一次性的，而是分散在未来几个月甚至几年里，每次只花你15分钟，你根本感觉不到自己在流血。

你想想看，你写一个工具函数，被调用了1000次，你会觉得”写这个函数浪费时间”吗？不会啊，你觉得这是理所当然的——一次封装，到处调用，这就是编程的核心思想。

文档是一模一样的道理。

文档就是你大脑里的函数封装。

你脑子里有一段关于缓存策略的知识——输入是”同事的问题”，输出是”15分钟的讲解”。不写文档，等于你把这段逻辑写成了内联代码：每次有人调用，你就得亲自执行一遍。写成文档，就是把它封装成一个函数：调用方只需要看文档（接口说明），不需要你本人来跑这段逻辑。

而且这个”函数”还有一个代码做不到的超能力——它可以被20个人同时并发调用，而你只需要”执行”一次。

这投入产出比，写代码都不一定有这么高。

8.4小时：你不知道自己每周浪费了多少时间

“行吧，道理我懂，但到底有多浪费？给我个数字。”

行，上硬菜。

Stripe做过一个内部调研，结论挺扎心的：他们的工程师每周平均花8.4个小时在”寻找信息和等待别人回答”上。

8.4个小时。一周按40小时算，五分之一的时间花在”找答案”上。不是写代码，不是做设计，不是调bug——就是单纯地找信息。

在Slack里翻聊天记录，在代码仓库里grep关键字，走到同事工位上问”那个接口的参数格式是什么来着”。

这8.4个小时里面，有多少答案其实已经存在了？在某个人的脑子里，在某次会议的讨论里，在某个PR的评论里——就是没有变成一份可以搜索、可以链接、可以转发的文档。

再来一个更狠的数据。Google内部统计过，一份好的设计文档（Design Doc），被阅读的次数平均是被修改次数的50倍。

你写了1次，50个人读。

把这个数字代入ROI公式算一下：

• 投入：你花1小时写一份文档
• 单次回报：每个读者省10分钟（不用来找你问了）
• 总回报：50人 x 10分钟 = 500分钟 ≈ 8.3小时
• ROI：（8.3 - 1）/ 1 = 730%

你去看看理财产品，年化收益能到10%就烧高香了。文档的ROI是730%。而且这还是保守估计——那份文档可能活好几年，读者远不止50人。

如果你是一个”不喜欢做亏本买卖”的程序员，写文档是你能做的最赚的事。

不只是ROI，还有复利

更可怕的是，文档的回报不是一次性的，它是复利的。

一份好文档不只是省了别人找你问的时间，它还会触发连锁反应。

小王看了你的缓存文档，不用来问你了——省了你15分钟，也省了他鼓起勇气走过来的社交成本。然后小王基于你的文档写了新接口的缓存处理，在PR里贴了你的链接。代码审查的人点进去看了，也搞懂了设计意图。一份文档，同时服务三个人。

半年后来了个新人，在Wiki里搜”缓存”，直接找到了你的文档。不需要任何人带他，自己就搞懂了。而你——可能早忘了这事了。

更妙的是，两年后你自己换了个项目，回头要看当初的设计思路。打开自己写的文档，五分钟就想起来了。你写的文档，最后连你自己都服务了。

这就是复利。你封装了一个函数，每多一个调用方，你当初写那几行代码的价值就又涨了一截。文档也一样——每多一个读者，你当初花的那30分钟就又赚了一笔。

你以为写文档要2小时，其实5分钟就够了

“好吧，我承认文档有用。但一想到要写文档，脑子里浮现的就是那种目录齐全、排版精美、图文并茂的技术文档，光想想就累了。”

问题就出在这儿。你把”写文档”的门槛想得太高了。

你不需要写一个RFC。你不需要写一个完美的技术方案。你需要的是一个最小可行文档——就像MVP一样，先上线，有人用了再迭代。

这是我的模板，5项内容，核心场景20分钟搞定，简单的5分钟就行：

1. 标题 + 一句话总结 「订单服务的两级缓存策略——本地缓存+Redis，用版本号控制一致性」

2. 背景 为什么要做这个？「高峰期订单查询QPS到了5000，直接打DB扛不住，加了两级缓存」

3. 做了什么（3-5个bullet point）

• 一级缓存：Caffeine本地缓存，容量1000，过期5分钟
• 二级缓存：Redis，过期30分钟
• 一致性：写入时递增version字段，读取时对比version
• 降级：Redis不可用时fallback到DB直查

4. 怎么用 「查看 OrderCacheService.java，核心方法是 getOrderWithCache()」

5. 注意事项（踩过的坑）

• 本地缓存不能设太大，JVM内存会爆
• Redis过期时间别设整数分钟，要加随机偏移防雪崩

再举个前端的例子，更简单：

标题：前端环境变量配置说明 背景：新人每次都搞不清楚.env文件怎么配 做了什么：整理了dev/staging/prod三套环境的变量表 怎么用：复制.env.example，改对应的值就行 注意事项：NEXT_PUBLIC_开头的才会暴露给浏览器，别把密钥放进去

就这么多。不需要目录。不需要完美排版。不需要配图。写在团队Wiki里，往群里发个链接。下次有人问，你回复一个URL就行。

你看，文档的门槛不是”两小时写一份完美文档”，而是”五分钟写一份够用的文档”。用程序员的话说：你不需要一上来就写一个高度抽象的通用框架，先写一个能跑的函数就行。

文档不是债务，是资产

大多数程序员把文档当成一种债务——”我应该写但没写”，带着负罪感。每次有人在周会上提起”我们文档是不是太少了”，全场沉默三秒，然后话题自动跳过。下周继续不写。

换个角度想：文档不是债务，是资产。

每写一份文档，你就在自己的”知识银行”里存了一笔定期。它会持续产生利息——每次有人读到它，省下的时间就是你的利息收入。

你写的那5个小时口头解释？那就是被通胀吃掉的现金——说完就没了，不产生任何复利。

而30分钟写出来的文档？那是一笔不断增值的存款。

所以我的建议是：从今天开始，每次你发现自己在口头解释同一件事第二遍的时候，停下来，花5分钟把它写成文档。不用完美，不用齐全，只要把刚才嘴上说的东西打成字。

这5分钟，是你作为程序员能做的回报率最高的投资。别再把知识内联在脑子里了——封装一次，让全世界调用。

没有之一。