浅谈作为程序员如何写好文档：了解读者

news2024/10/7 11:20:52

我作为从一名懵懂的实习生转变为工程师的工作经历中，伴随着技术经验的成长，也逐渐意识到了编写文档是知识和经验传递给其他人的最有效方式。通过文档，可以分享我的技术知识和最佳实践，使其他人更好地理解我的工作。在这里，给大家浅谈一下作为技术研发如何写好技术文档😄

为何了解读者

在日常写文档过程中，大部分技术同学不会花太多时间去了解“读者”。然而由于缺乏对读者对了解，大部分的技术文档的“可用性”是很差的。

“可用性良好”的文档：主要是指读者能看懂文档内容，并且读者能借助文档顺利达到他的目的。比如完成一个任务或者了解一个概念。
反之，“可用性不好”的文档，即使读者能看懂文档，可能也没有办法帮助他解决问题。举个栗子：

写给小白的技术文档，充斥着艰深的术语，又没有任何术语解释。
写给运维工程师的文档，不重点介绍运维操作，却花大篇幅去介绍技术原理。

何为了解读者

明确读者身份: 文档最终的读者是小白用户or资深用户？或者是运维人员or开发人员? 确立文档的受众是第一步。
明确读者阅读目的:该文档是为了让读者了解一个概念、完成一个步骤,还是查阅一个参数解释。先确立了文档的目标，才能保证写文档时的大方向不会走错

举个例子: 某绘图软件的用户手册
- 文件菜单按钮:用于创建新文件,打开文件,重命名文件等
- 裁剪按钮:用于裁剪出图片中选中的区域
- …
该文档作者很详细的描述了界面上各个控件的功能，但是该文档与其说是“用户手册”，不如说是“功能清单”。用户很难找到他所需要的内容。
基于读者视角，该文档应该介绍这个软件可以解决的具体问题。绘图软件的目标读者一般都是设计人员，那么他们的阅读目的就是完成绘图的各个步骤。修改后的版本，应该使读者快速定位到有用的内容：
- 如何捕捉图片
- 如何选择背景
- 如何绘制椭圆形和圆形
- …
明确读者所需信息:根据读者的认知能力提供所需信息。比如目标用户是小白，则不能写的过于艰深。
针对不同的读者群体，应该提供差异化的内容，不同认知水平的读者，所拥有的信息水平也是不同的，即“信息差”。对于文档写作者和读者的信息差，写文档时应该尽量去弥合信息差，将读者的认知水平拉齐到和作者一样的高度。

The curse of knowledge(知识诅咒/知识陷阱)：你越是深入到了解一样东西，则你越难体会/不了解他人的状态。

很多时候我们难以意识到“信息差”的存在。在写文档时尤其注意需要补充这些读者不知道，却又必须知道的关键信息，否则容易导致文档的不可用。

常见的信息差来源——术语

我们在使用术语时，一定要注意术语的规范性。例如以下文档：
- 大池子
- 肉鸡
- CPU打到60%
此类文档就是把一些“行业黑话”当成术语写在文档里面。这是应该尽力避免的。
其次，同一个术语应该尽量用同一个意思来表达，比如“接口”，有的人喜欢叫“API”，有的人喜欢叫“方法”。那么在同一篇文档里，应该统一用接口或者统一用API，不能换来换去，避免读者造成不必要的困惑。
最后，应该在文档中提供及时的术语解释。例如用超链接，引用，注释块等技巧。可参考以下文档：
- 允许您创建消息组以适应不同的业务场景，在不同的国家或地区，可以使用签名和可用的模板
- 签名：指在文本消息正文之前的xxx，用于识别公司业务
- 模板：…
常见的信息差来源——相似物

当一个产品提供了两个相似的功能，文档需要帮助读者辨析，方便其做出选择。例如通过表格对比的方式列出两个产品的不同点：

常见的信息差来源——新事物

作为技术研发，我们不管是在交代步骤还是在解释概念时，所有新出现的事物都需要充分解释其来源。
下例文档详细交代了如何获取AppID、AppName和region。这些信息一旦缺失,就可能影响客户满意度、并带来额外的客户支持成本。