大爷说:你写的文档,到底是给谁看的?

▌ 导读

前几天村口碰见老王，满脸委屈说项目组写了一堆文档，结果新来的同事还是一个个来问他。大爷喝了口茶，问他：”你写那些文档，到底是给谁看的？“老王愣住了。这个问题，很多技术团队压根没想过。

一、文档死在”写完就算完”

很多团队的文档，说白了是写给自己看的——更准确说，是写给”当时的自己”看的。

写文档的人脑子里装着所有上下文。他知道这个模块为啥这么设计，知道这个字段的历史包袱，知道那个接口藏着什么坑。所以他写出来的东西，对他来说是完整的，对别人来说是天书。

▎ 隐含的知识不会自动跑进文档。而那些隐含的知识，偏偏是新人最想要的部分。

结果就是：一套文档，只有作者自己能读懂，对外形同虚设。

二、写给”检查员”而不是”使用者”

还有一种文档，写得规规整整，格式漂亮，章节齐全。看起来很认真，其实是为了应付流程——满足”我们有文档”这个检查项。

这类文档的目标读者，是季度总结PPT里的那张截图，不是真正需要信息的工程师。

于是你会看到这种描述：

▎ 本系统采用微服务架构，具备高可用、高性能、高扩展性，遵循SOLID原则…

这段话什么问题都没解答，但每个字都显得很专业。真正的使用者看到这里，只会默默关掉页面，然后找人问。

三、没回答”我最可能问的问题”

好文档的本质，是提前回答了读者最可能提的问题。

新人接手一个模块，他不关心”这个系统的架构理念是什么”，他想知道：我怎么在本地跑起来？这个接口报错了怎么查？这个配置项是干嘛的，我能改吗？上次那个XXX问题怎么解的？

但大多数文档，回答的是写文档的人”觉得重要”的问题，不是读者真正会问的问题。

► 文档的价值，不在于写了多少，而在于替读者省了多少麻烦

四、怎么写才有人用？

这不是文笔问题，也不是模板问题，是视角问题。

①先定读者，再动笔
写之前问自己：这份文档是给谁用的？他是新人还是老手？他什么时候会来看？他来了最迫切想知道什么？架构决策文档和快速上手指南，根本不是一种东西，别混着写。

②用”场景驱动”代替”结构驱动”
别按你理解的知识结构来组织，按读者会遇到的场景来：第一次部署怎么做？排查XXX类型的问题从哪查起？修改XXX功能需要动哪里？每个场景都是一个入口，读者带着具体问题来，能直接找到答案，下次才会再来。

③让文档”会过时”而不是”不更新”
死文档比没文档危险。过期的部署步骤，会直接让人踩坑。每个核心文档加一行：最后验证日期：XXXX-XX-XX。没人更新的文档，就是在提醒读者”这东西可能过期了，自求多福。”比假装永远正确，要诚实得多。

五、文档的最高境界：让人找不到你

大爷干了二十年，评判文档好不好，就一个标准：这份文档存在之后，来问你的人变少了没有？

好文档替你挡掉80%的重复问题。剩下20%，才是真正值得深聊的。烂文档不减少任何问题，还会让人觉得”文档都有了为什么还不会”，给团队添堵。

📝 写在最后

文档写不好，根不在技术能力，是没站在读者角度想过一次：他是谁，他什么时候来，他来了最想知道什么。

这三个问题想清楚，再动笔，结果不一样。

大爷见过太多团队，一边花时间维护一堆没人看的文档，一边花更多时间靠口口相传传递知识。两头的力气合起来才够用，偏偏都在白费。

💬 互动时间

你们团队有没有”写了没人看”的文档？问题出在哪？欢迎评论区聊聊，大爷认真看每一条。