《如何写作通用教程》将通用写作拆解成五个部分，总结了在写作前 、写作中 和写作后三个阶段需要注意的写作要点和技巧，通读整个系列文档，可以帮助你搭建系统的技术写作知识体系。
第一章：为何要了解读者
在专业的技术文档写作中，文档工程师需要在项目前期花相当一部分时间去了解读者，例如，做用户画像、用户旅程，拜访典型客户等，以保证文档的可用性（usability） ，即保证读者能够理解文档、并借助文档顺利完成任务。
然而，在研发同学日常的写作过程中，极少有人专门花时间去了解文档的读者。例如，写给小白用户的入门文档，充斥着行业术语，且无明确定义；写给运维工程师的文档，不重点介绍运维操作，却花大篇幅描述技术原理。这些问题往往会影响文档的可用性，导致读者无法看懂文档，或无法通过文档解决具体问题。
第二章：何为了解读者
了解读者，可以从这三个方面入手：
- 明确读者身份。例如，是小白用户，还是资深用户？是运维人员，还是同组的开发同事？
- 明确读者的阅读目的。例如，读者阅读你的文档，是为了了解一个概念、完成一个步骤，还是查阅一个参数解释？
- 明确读者所需信息。如果不确定读者是否预先了解，比较保险的做法是将信息写全。
明确读者身份
大多数情况下，我们的目标读者是单一的，比如上下游的同事、或者客户。但有时我们也会遇到一些复杂情形。例如，一套直播产品的文档，有些内容是给主播看的，有些是给搭建直播间的 IT 同学看的，还有些是给做二次开发的开发者看的。遇到这种复杂的情形，我们一定要确认好文档的目标读者是谁，否则文档容易出现鸡同鸭讲、不知所云的情况。
明确读者的阅读目的
很多同学在写文档时容易陷入"自嗨"，忽视目标读者实际的需求，这会极大的影响文档的可用性。比如，大量的信息对读者来说是无用的，而有用的信息反而需要费力地去寻找。
🌰 例子：以下表格列出了一个绘图软件的两种文档写法：
- 左侧为典型的"自嗨"型写法。作者沉迷于描述软件各个按钮的功能。该文档与其说是用户手册，不如说是功能清单。
- 右侧基于用户视角，介绍这个软件可以解决的具体问题，如捕捉图片、选择背景，用户可以从具体需求出发，快速地定位到有用内容。
| 修改前（自嗨型写作） | 修改后（用户视角） |
|---|---|
| 文件菜单按钮：用于创建新文件，打开文件，重命名文件等 | 如何捕捉图片 |
| 裁剪按钮：用于裁剪出图片中选中的区域 | 如何选择背景 |
| ... | 如何绘制矩形 |
明确读者所需信息
在写作中，要特别留意与读者的信息差（knowledge gap） 。国内的研发同学通常比较有韧劲，对文档的容忍度也比较高，但同时对读者的预期也较高，经常想当然的认为某个背景知识是众所周知的、无需解释的。但事实上，这种"想当然"常常导致文档"没头没尾"，读者很多时候需要靠"猜"来补全信息。
🌰 例子：以下表格列出了一个海外文档的修改过程：
-
左侧是研发提供的第一稿，极其言简意赅、晦涩难懂。
-
右侧是文档工程师改写后的版本，增加了以下内容：
- 在哪里设置 tag
- 设置的操作步骤
- 需要给哪些主机设置 tag
- 示例
当然，我们还可以视情况添加更多内容，如为什么要设置 tag、设置后会得到什么结果等。
| 修改前（缺乏必要信息） | 修改后 |
|---|---|
 |
 |
另外，给大家介绍几个较为常见的容易出现信息差的地方，日常写作中可以特别留意：
| 信息差 | 详情 | 示例 |
|---|---|---|
| 术语 | - 使用标准的术语 - 同一个意思尽量用一个词表达 - 可以通过链接或悬浮提示的方式提供术语解释 | 🌰 例子 ：下方列举了后端开发同学在文档中使用的一些黑话。这些黑话在任何类型的文档中都不应该出现： 🌰 例子 ：下方截图提供了术语的悬浮提示，读者可以方便地查阅术语释义。飞书的百科功能也能达到相同效果。 |
| 相似物 | 如果一个产品提供了两个相似的功能，文档需要帮助读者辨析，方便其作出选择。 | 🌰 例子 ：下方为一个产品 SaaS 接入方案与 aPaaS 接入方案的功能对比。曾经有许多客户将这两个方案混为一谈，甚至想当然的认为两者支持的功能是完全相同的。提供该表格之后，此类误解显著减少了。 |
| 新的事物 | 所有新出现的东西都需要充分解释其来源，例如，如果步骤中新出现一个文件路径，就需要交代这个路径是从哪里得来的。 | 🌰 例子 ：下方为一个 SDK 的接入说明。作者详细交代了如何获取"直播活动 ID" 、"Token"，以及如何获取 AppID、AppName 和 region。这些信息虽然零碎，但缺一不可。一旦缺失，就可能影响客户满意度、并带来额外的客户支持成本。  |
第三章：如何了解读者
那么，如何快速地建立起对读者的认识呢？以下提供了文档工程师较为常用的几种方法，大家可以挑适合自己的方法一试：
拉近与读者的距离
接触读者的几类途径：
- 邀请同事评审：如果不容易找到真实的读者，最简单的办法就是把身边的同事作为目标受众，让他们从读者的角度给出反馈意见。
- 读者访谈： 例如，如果你需要给上下游部门的同事写文档，可以直接与他们约一次访谈，了解他们对文档的期待、建议和意见。
- 用户支持群： 和客户支持/客户组建文档支持群，收集第一手的文档问题。这是一个长期、可靠、优质的渠道，通过该途径可以收集到许多鲜活的、高价值的文档反馈。
时常问自己这些问题
在动笔写文档之前，建议大家做一次头脑风暴，想象出完整的读者旅程。头脑风暴的同时，你可以问自己这些问题：
-
读者从哪里来：
- 这件事情的背景是怎样的？
- 读者现在遇到了什么困难，或者要完成什么任务？
- 读者最开始是一个什么状态？TA 此时在做什么，TA 手边有哪些资源？
-
读者在哪儿：
- 读者这个时候是一个什么状态？比如，读者此时应该在哪个文件夹下？
- 读者怎么确认 TA 是处于文档里说的这个状态？比如，执行某个命令，应该返回什么结果？
-
读者到哪里去：
- 然后呢？ 为什么要告诉读者这些信息？
- 这个东西读者能用在哪里？
- 读者下一步要做什么？
这些问题的主要目的，是让读者在走进文档这片大森林的时候，知道自己在哪里，从哪里来，到哪里去。就像一个指路牌，让旅人在前进的时候更有信心。甚至可以基于此做一个 checklist，提醒自己不要漏掉某一部分信息。
第四章：小结
本节课程主要介绍了以下内容：
- 了解读者的必要性
- 了解读者的三个切入点
- 了解读者的各种手段
了解读者并不是一件容易的事情，若要真正深入研究，还需要用到用户画像分析、心理学分析等专业知识。本文介绍的只是较容易执行的一些方法，希望能够对经常写文档的同学有所助益。