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

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

为什么了解读者

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

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

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

什么是了解读者

1. 明确读者身份: 文档最终的读者是小白用户or资深用户？或者是运维人员or开发人员? 确立文档的受众是第一步。

2. 明确读者阅读目的:该文档是为了让读者了解一个概念、完成一个步骤,还是查阅一个参数解释。先确立了文档的目标，才能保证写文档时的大方向不会走错

   举个例子: 某绘图软件的用户手册

   • 文件菜单按钮:用于创建新文件,打开文件,重命名文件等
   • 裁剪按钮:用于裁剪出图片中选中的区域
   • …

   该文档作者很详细的描述了界面上各个控件的功能，但是该文档与其说是“用户手册”，不如说是“功能清单”。用户很难找到他所需要的内容。
   基于读者视角，该文档应该介绍这个软件可以解决的具体问题。绘图软件的目标读者一般都是设计人员，那么他们的阅读目的就是完成绘图的各个步骤。修改后的版本，应该使读者快速定位到有用的内容：

   • 如何捕捉图片
   • 如何选择背景
   • 如何绘制椭圆形和圆形
   • …

3. 明确读者所需信息:根据读者的认知能力提供所需信息。比如目标用户是小白，则不能写的过于艰深。
   针对不同的读者群体，应该提供差异化的内容，不同认知水平的读者，所拥有的信息水平也是不同的，即“信息差”。对于文档写作者和读者的信息差，写文档时应该尽量去弥合信息差，将读者的认知水平拉齐到和作者一样的高度。

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

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

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

   我们在使用术语时，一定要注意术语的规范性。例如以下文档：

   • 大池子
   • 肉鸡
   • CPU打到60%

   此类文档就是把一些“行业黑话”当成术语写在文档里面。这是应该尽力避免的。
   其次，同一个术语应该尽量用同一个意思来表达，比如“接口”，有的人喜欢叫“API”，有的人喜欢叫“方法”。那么在同一篇文档里，应该统一用接口或者统一用API，不能换来换去，避免读者造成不必要的困惑。
   最后，应该在文档中提供及时的术语解释。例如用超链接，引用，注释块等技巧。可参考以下文档：

   • 允许您创建消息组以适应不同的业务场景，在不同的国家或地区，可以使用签名和可用的模板

   • 签名：指在文本消息正文之前的xxx，用于识别公司业务
   • 模板：…

   常见的信息差来源——相似物

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

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

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

如何了解读者

了解读者的阅读目的以及所需信息也是至关重要的。
当我们有足够的时间和精力，可以尝试主动走近读者：

• 邀请同事评审
  把身边同学作为目标受众,获得反馈意见。最后再对文档进行反复修改，反复打磨。
• 读者访谈
  与读者约一次访谈,了解他们对文档的期待、建议和意见。
• 文档支持群
  建立文档支持群,收集第一手的文档问题。这是一个长期、可靠、优质的渠道,通过该途径可以收集到许多鲜活的、高价值的文档反馈。

当然，如果没有条件，则可以选择第二种路径，即在动笔写文档之前，做一次头脑风暴，想象出作为读者的阅读历程：

• 读者从哪里来?
  写此文档背景是什么?读者遇到了什么困难,要完成什么任务?读者最开始是什么状态?他们此时在做什么,手边有哪些资源?
• 读者在哪儿?
  想象读者此时所处状态?比如,此时在哪个文件夹下?读者怎么确认他们处于文档里说的这个状态?比如执行某个命令,应该返回什么结果?
• 读者到哪里去?
  为什么要告诉读者这些信息?对他们有什么用?读者下一步要做什么?

总结