如何了解读者 | 豆包MarsCode AI刷题

ruogu_coder
65 阅读12分钟

了解读者是整个写作过程的基础，决定了你最终要写什么内容，下面我会按照“是什么、为什么、怎么做”这三方面向大家介绍：

1. 了解读者的重要性（是什么）

在日常写作中，大部分同学其实不会花费太多时间在这个上面，要么是觉得这不重要，要么是觉得自己已经足够了解读者了，然而很多时候由于不了解读者，缺乏认识，我们写出来的文档的可用性是很差的。

那什么样的文档是可用性的文档呢 ？

可用性文档的定义

  • 可用性强的文档：读者能够看懂内容，并且能够借助文档顺利达到目的，如完成任务或理解概念
  • 不可用的文档：读者看不懂或即使看懂了也无法解决问题。
    • 比如写给小白用户的入门文档，充斥着艰深的术语，又没有任何的术语解释，那么这个文档必然可用性是很差的；写给运维工程师的文档，不重点介绍运维操作，却花大篇幅去介绍技术原理。

所以，为了写出可用性强的文档，需要深入了解读者的需求和背景

2. 了解读者的必要性（为什么）

2.1. 明确读者身份

首先是确定读者的身份，是小白用户还是资深用户呢？是运维人员还是同组的开发同事呢？还有一些难以分辨的案例，比如一套直播的产品文档，有些内容是给主播看到，有些内容是给搭建直播间的 IT 同学看的，还有些是给二次开发的开发者看的，遇到这种复杂的情形，需要花时间去确定好你的这篇文章的受众是谁。

2.2. 明确读者的阅读目的

明确读者阅读目的，是了解一个概念或者完成一个步骤还是查阅一个参数的解释。了解完目的，才能够保证你的大方向不走错，那么如果我们不了解读者的阅读目的，会发生什么呢？

我们很容易陷入自嗨型写作，比如按照自己的思路，写一大堆读者用不上的东西，还觉得自己写的很好，比如刚才运维文档的例子，其实很常见，研发同学在开发完一款应用之后，会写一个运维手册，供后面的运维同学去查阅，但是因为他非常地欣赏自己的产品设计，所以 70%的内容都在描述他当时都设计思路 和技术原理，那等到运维工程师真的遇到线上故障的时候，来查询这个运维手册，发现满篇文章都是设计思路，会非常的痛苦，因为他其实并不关心这些，他只关心怎么快速把线上故障解决。举个例子：

修改前

文件菜单按钮：用于创建新文件，打开文件，重命名文件等

裁剪按钮：用于裁剪出图片中选中的区域

修改后

如何捕捉图片

如何选择背景

如何绘制矩形

如何绘制椭圆形和圆形

这是一个绘图软件的用户手册 ，在修改前的版本，作者很详细地去描述了界面上各个控件的功能，该文档与其说是用户手册其实不如说是功能清单，用户很难快速地找到他所需要的内容，而修改后的版本，则是基于读者(设计人员)视角，来介绍这个软件可以解决的具体问题。绘图软件目标读者一般都是设计人员，那么他们的阅读目的应该是很清晰的，就是完成绘图的各个步骤，比如捕捉图片，选择背景修改后的版本，读者可以快速地定位到有用的内容，那么这个文档的可用性就大大提高了！

2.3. 明确读者所需信息差

除了明确读者阅读目的以外，我们还需要根据目标读者的特点，来明确文档需要提供哪些信息，当你确定了你的目标读者是小白用户之后，则内容不要写的过于艰深，对任何术语都要提供详细的解释，反之如果是高阶用户则相关的基础信息就可以少交代一些。

文档到底要提供哪些信息，如果要展开说的话，其实是一个很宏大的命题，比如针对不同的读者群体，我们如何去提供差异化的内容，在大家都日常写作中，大部分遇到的还是比较单纯的情形，目标读者也是比较单一的，所以这里就只提一个比较基础的点，就是信息差。

信息差还有一种叫法叫信息不对称，专业的定义是社会上不同阶层的人，拥有的信息是不同的。

那掌握信息比较充分的人员往往就会处于一个比较有利的地位，而且可以利用这个差异，来获取一些好处，尤其商业场景上，而这里我对信息差作一个狭义的定义，就是作者和读者之间的认知差异，说得再通俗一点，就是作者知道而读者不知道的东西。和商业上不同在写文档的时候，我们需要尽量地去弥合信息差，将读者的认知水平拉齐到和作者一样的高度，这样才能够保证读者读得懂。

学术上还有一个比较有意思的概念，就是 知识诅咒或者说知识陷阱(the curse of knowledge)。

指的是你越是深入地了解一样东西，你越难体会不了解它的人的状态，而很多时候，我们会意识不到这个信息差的存在，在文档中遗漏了这些读者不知道，却又必须知道的关键信息，而导致文档的不可用，我们再举一个例子：

修改前：

Step tag：

1.  info .hxxx

修改后：

Tagging the xxx hosts.

In the xxx system,tag the xxx hosts that you have prepared in Prerequisite.

a.Log into xxx,and the create a new tag for your cluster.In this example,we create the xxx.default tag.

b.Add the IP address of the xxx hosts under the tag. In this example,we use the following hosts:

1.  info xxxx

这是一份国内运维同学写给国外运维同学写的运维手册，截取的是一段主机设置 tag 的说明，国内的运维同学对整个产品和运维平台是非常熟悉的，所以他根本没有意识到他需要交代很多背景信息，但国外的运维同学是完全不了解这个产品和运维平台的，所以他肯定会有非常多的疑问，首先为什么要给主机设置 tag 我不设置会有什么后果呢？其次应该在哪里设置 tag 如果是在某个平台上的话那这个平台的链接是不是要交代一下，最后不同的主机是否需要设置不同的 tag 如果是的话那规则又是什么呢？经过文档工程师的修改，这些问题呢都得到了解答，这个文档交付给国外的运维工程师之后，没有再收到后续的和设置 tag 相关的问题了，那这个文档，我们就认为是一个很好地弥合了信息差的文档。这里再给大家介绍几个比较常见的信息差来源，大家在写作中，可以特别地去留意这几个点

1、 术语

我们在使用术语时，一定要注意术语的规范性，下面的这几个 Bad case：

Bad case：

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

就是非常典型的把日常的行话当成术语来写在文档里面，这个是我们要尽力避免的，其次呢同一个意思尽量用同一个术语来表达，确实有很多东西是不止有一个标准的说法的，例如：接口有的人喜欢叫 API y 有的人喜欢叫方法，那在同一篇文档里，我们统一用接口或者统一用 API ，不要换来换去造成读者不必要的困惑，最后提供及时到术语解释，例如在术语出现的地方，加上一个术语解释的链接，甚至是做一个悬浮的提示，比如飞书的百科功能，对读者都是很大的帮助，这里再举一个 Good case：

Good case

允许您创建消息组以适应不同的业务场景。

在不同的国家或地区，使用的签名和可用的模板。

签名-指在文本消息正文之前的XXx,用于识别公司或业务。

2、 相似物

我们在描写到两个相类似的东西时，例如一个 SDK 提供的两个相似的接口，就一定要解释清楚两者都区别，不能模棱两可，不然读者只能凭着感觉走，就很有可能做出错误的选择，这里再举一个例子：


为满足您对原生环境的开播与观播需求，企业直播将相关底层能力整合包装，输出了一套支持在您自身产品独立接入的aPaaS方案即Android SDK、iOS SDK和Web SDK。SaaS方案和aPaaS方案的企业直播观播页面存在一定的功能差异，具体支持情况见下表。

说明：iframe嵌入能力与SaaS方案相同。详情请参见iframe嵌入。
功能说明Sass 方案(PC + 移动端)Android SDK && IOS SDKWeb SDK
自定义观看域名使用专属域名观看直播支持不适用支持
社交平台分享观众可以将直播分享至微信、飞书等各大平台。支持二维码分享和复制观看地址。支持支持支持

这是一款直播产品的两个接入方式的功能对比，在没有这个表格的时候，会遇到一些客户，选择某个集成方式，开发到一半发现他要的某个功能在这种集成方式下是不支持的，那就非常尴尬了。

3、 新事物

我们不管是交代步骤还是解释概念，在碰到新的事物时，一定要充分地去解释其来源，举例：

下例文档详细交代了如何获取AppID、AppName和region。,这些信息一旦

缺失，就可能影响客户满意度、并带来额外的客户支持成本。

@Override
public String getAppID(){
    return mAppId;//申请TTSDK License时使用的AppId,请联系技术支特获取。
}

@Override
public String getAppName(){
    return mAppName;//申请TTSDK License时使用的AppName,请联系技术支持获取。
}
@Override
public String getAppRegion(){
    return mRegion;//申请TTSDK License时使用的region,即china。
}

这是一份 SDK 集成文档，在解释这几个字段时，文档中都会特别地去说明读者可以通过何种途径来获取这几个字段的值，这里面凡是少交代一个信息，都可能导致客户流失，产品满意度下降，或者造成额外的客户知识成本。

3. 如何了解读者（怎么做）

现在我们清楚了为什么要了解读者，什么是了解读者，那一定会有人问我们应该如何去了解读者呢？尤其是如何去知道读者的阅读目的以及所需要的信息呢，这里给大家提供两类途径。

3.1. 主动走进读者

主动地去走近读者，当然这个要求我们有足够的时间和精力，去做这个事情。

3.1.1. 邀请同事评审

如果你能找到目标读者来评审你的文档，那自然是极好的，如果不容易找到真实的用户，你可以把身边的同事作为目标受众，让他们从读者的角度来给出反馈意见，反复修改，反复打磨。

3.1.2. 读者访谈

者访谈，例如如果需要给上下游部门的同事写文档，可以直接与他们约一次访谈，了解他们对文档的期意见和建议。

3.1.3. 文档支持群

文档支持群你可以让你的读者把所有的文档相关的问题，抛到一个群里面，那我们就可以从这个群里面收集，第一手的文档问题，这通常会是一个比较长期可靠且优质的渠道，通过该途径可以收集到许多鲜活的、高价值的文档反馈。

3.2. 头脑风暴

如果没有办法做到前面所说的这些尝试，可以选择第二种路径(头脑风暴)，就是在动笔写文档之前，做一次头脑风暴，想象出完整的用户旅程，头脑风暴的同时，你可以问自己这些问题：

  • 读者哪里来
  • 读者在哪里
  • 读者哪里去
  1. 读者哪里来（用户旅程的起点） ：
    • 目的：理解读者的背景和他们为何会寻找这篇文档。
    • 内容：在这个阶段，你需要思考读者在遇到文档之前可能遇到的问题或他们想要完成的任务。这有助于确定文档的目标受众和他们的需求。
  1. 读者在哪里（用户旅程的当前位置） ：
    • 目的：确认读者在阅读文档时的当前状态。
    • 内容：在介绍复杂或多步骤的流程时，你需要在关键节点上帮助读者确认他们是否处于正确的状态。比如他们应该处于的界面或执行某个命令后应该得到的结果。这样做可以增强读者的信心，确保他们按照正确的步骤前进。
  1. 读者哪里去（用户旅程的终点） ：
    • 目的：指导读者完成文档后应该采取的下一步行动。
    • 内容：在文档的结尾，提供有用的资源，如文档链接或其他指导，帮助读者了解如何继续他们的旅程。这有助于读者在完成当前任务后，知道接下来应该做什么。
avatar
文章
阅读
粉丝