别人不写设计文档，我写了，所以我吃亏了？

Posted 2020-12-21

《如何写技术文档？》的评论让人感到意外，一篇关于“如何写好设计文档”的文章，评论里充斥着各种戾气。

不确定自己的理念，在互联网新时代，是否已经过时，似乎写文档成了少数派。无论如何，旗帜鲜明的表达一下自己的看法。

本文所有观点均为个人观点，不存在任何“评判”，分享自己认为正确的观点。
画外音：后文中的素材，截图自《如何写技术文档？》的评论，隐去了头像和名称。

一、

《如何写技术文档？》评论里，点赞最多的观点是：不写技术文档，是因为只有这样，老板才不敢随便替换ta，让ta具备“不可替代性”。

然而，“职场不可替代性”
不是指：
“我埋了很多隐藏坑，只有我知道隐藏坑在哪里，所以我不可替代”。

而是指：
“我具备其他人不具备的核心竞争力，可能是态度，可能是专业能力，也可能是长得帅”。

阳光正能量：

在职场冥思苦想，通过“挖坑”来保住自己的“铁饭碗”，不如努力提升自己的核心竞争力，让自己具备到哪里都有饭吃的能力。

二、

第二类观点是：文档是写给别人看的，给老板，给客户，给要沟通的人，要接手项目的人。项目参与者本身不需要写文档。

为什么要写设计文档？

对自己，让自己在动手写代码之前，帮助自己想得更清楚；
对项目，保证信息的一致性，保证项目的可控性，减少项目风险；
对团队，确保知识的沉淀与传承；

项目涉及多少个子系统，每个子系统涉及多少个模块，模块间的依赖关系如何，彼此要提供多少个接口，每个接口的参数如何，接口实现过程中上下游交互如何，核心逻辑用什么技术方案实现… 难道相关技术人都一清二楚么？

很多自信的技术大神，“以为”懂了，但却讲不明白，其实就是不懂。
很多“讲得明白”，却“写不清楚”，其实就是没懂透。
把一个项目，一个技术问题，按照逻辑，用文字来一遍，才表示真正的想清楚了。
画外音：落地到纸面，能发现设计中的很多问题。

文档如何保证信息的一致性，减少项目风险？

举个简单的例子，php工程师要提供一个获取订单信息的HTTP接口，后期要与ios/android/FE工程师联调，同时QA工程师也需要测试。

难道不需要把HTTP接口落地到纸面么？

http://daojia.com/order/getinfo?oid=${oid}
cookie: uid=${uid}
cookie: token=${token}
…
RESTFUL接口格式，输入输出格式，这些信息是PHP/IOS/Android/FE/QA工程师们都需要明确的信息，否则相关研发联调测试工作就无法展开，这些信息，难道每次都需要口头沟通么？

项目上线1年后，接口要迭代升级，难道每次都需要去代码里查么？
画外音：注释很重要，注释与文档并不冲突，它们解决的并非同一个问题。

阳光正能量：

写好文档对自己，对项目，对团队都是有好处，何乐而不为呢？

三、

第三类观点是：没有时间写。

上帝是公平的，时间是守恒的，多花一些时间想清楚设计，编码一定能更顺畅，能够减少很多沟通/扯皮的时间，能够节省很多方案变更导致的额外的修改/联调/测试的时间，能够节省很多中长期维护的时间。

阳光正能量：

我想健身，但我没有时间。
我想学英语，但我没有时间。
我想写好文档，但我也没有时间。
刷朋友圈，刷头条，刷抖音，追连续剧，我有时间。
拒绝借口，一起行动起来，写好技术文档。

四、

还有一类观点：需求变化快，方案变化快，文档写得慢，于是，写文档没有用。

讨论一个事情，先讨论合理性，如果合理，但是有困难，再看有困难的解决方案，正常应该是这样的一个逻辑，对吧？

因为：
“需求变化快，方案变化快，文档写得慢”
所以：
“写文档没有用”
这个逻辑本身就是错的。

我们（特别是有话语权，决策权的技术leader）首先，难道不是应该想一想：

• 需求总是变，是否合理？
• 方案总是变，是否合理？
• 文档写得慢，是否合理？
• 没有文档，是否合理？
  难道不是应该先问自己这些问题么。

如果认为“文档写得慢不合理”，接下来，难道不是应该想一想：
为什么写得慢，是员工意愿不足，员工能力不足，工具不好用，还是其他原因？

• 如果意愿不足，如何提升员工意愿
• 如果能力不足，如何提升员工能力
• 如果工具不好，如何优化工具效率
  …

存在未必合理：

• “奴隶制度”存在了几千年，所以生之为奴就合理么？
• “需求总变，方案总变，没有文档”，但这些就一定合理么？

阳光正能量：

作为技术leader，你团队里的兄弟姐妹们在水深火热之中，你却不作为，你不愧疚么？请在自己能力范围内行动起来，去尝试改变不合理的现状，把技术氛围搞起来。

五、

一类观点：别人不写，自己写，亏了。

一类观点：老板需要文档，码农不需要。

一类观点：工资这么低，不写；涨工资，才写。

一类观点：写文档是成就别人。
画外音：评论太多，就不一一放出了，大家直接查阅《如何写技术文档？》底部评论吧。

一篇《如何写技术文档？》，在评论里大部分的观点是“写了没用”，这是我万万没有想到。
画外音：希望大家只是戏谑我，而不是真这么认为。

甚至，我会想，我一直坚持的东西，是对的吗？

2011年转岗，我认真做过一个“模块交接”，对当时负责的13个模块做了梳理和汇总，害怕自己转岗后，接手的工程师搞不定，而影响项目和模块，这样我会万分内疚。

甚至，在转岗几个月后，接手我模块的同事有疑问，我都会跑到同事工位，解答同事的问题。

结尾：

不管别人写不写文档，我觉得这是一件正确的事情，我就会去做。
不管别的leader要不要求写文档，在我的团队，我就会这么要求。

多年以后，或许你会发现，正是因为你做了和别人不一样的选择，你成了和别人不一样的你。

共勉！

架构师之路-分享可落地技术

相关推荐：

《如何写技术文档？》
《需求总是变，合理吗？》

调研：

对于不合理的事情，你的老板是否有作为？