Audience

课程设计者认为你对数学公式已非常习惯。因此，本单元始于如下等式：

好的文档 = 受众完成任务所需的知识和技能，即受众当前的知识和技能

换句话说，文档应该提供受众需要但未知的信息。因此，本单元主要内容为：

• 定义文档的受众。
• 确定受众要学习的内容。
• 为你的受众量身而写文档。

确定受众

严谨的文档作者会花大量时间和精力来定义受众。包括做调研、用户体验研究、焦点小组(focus groups)和文档测试。你可能没有那么多时间做完这些事情，故本单元教你一些更简单的方法。

首先确定受众的角色，可能的角色包括：

• 软件工程师
• 技术、非工程师角色（技术软件经理）
• 科学家们
• 科学领域的专家（例如，医生）
• 工科专业本科生
• 工科专业研究生
• 非技术职位

我们很高兴看到许多非技术职位的人有着不错的技术和数学能力。但是确定受众角色仍是定义受众的一阶近似值。同一角色的人通常有着相同的基本知识和技能。例如：

• 大部分软件工程师都知道流程的排序算法，大 O(*)复杂度表示法和至少一个编程语言。因此，你大可相信软件工程师知道 O(n) 的意义，但对非技术角色则不然。
• 针对医生的科研报告，与针对非专业受众的报纸文章看起来是完全不同的。
• 教授对研究生介绍的新机器学习算法的解释，应该不同于对一年级本科生的解释。

如果所有相同角色的每个人都有完全相同知识和水平，写作会容易得多。不幸的是，即使同样的角色，其知识范围也相差甚远: Amal是Python的专家，而Sharon是C++的高手，Micah则更擅长Java。Kara喜欢Linux，David则只熟悉iOS。

因此，角色并不足以定义受众。也就是说，同时也要确定受众的知识范畴。Frombusx项目的工程师可能对相关的Dingus项目有所了解，但对无关的Carambola项目一无所知。普通心脏专家比软件工程师会更了解耳朵的问题，但远不如听力学家。

受众分析范例

如下是虚构项目Zylmon的受众分析范例：

项目Zylmon的目标受众角色如下：

• 软件工程师
• 技术产品经理

目标受众的知识分析如下：

• 目标受众熟悉Zyljeune API，跟Zylmon API相似。
• 目标受众熟悉C++，但是没有使用过新的 Winged Victory开发环境构建过C++项目。
• 目标受众在大学学过线性代数，但是大部分团队成员需要重新了解矩阵乘法。

确定受众需要学习的内容

请列出目标受众需要学习哪些内容以实现文档目标的清单。某些情况下，列表需要包含受众需要执行的“任务”。例如：

After reading the documentation, the audience will know how to do the following tasks:

• Use the Zylmon API to list hotels by price.
• Use the Zylmon API to list hotels by location.
• Use the Zylmon API to list hotels by user ratings.

请注意，受众有时必须按特定顺序来掌握文档内容。例如，受众在学习编写程序前，需要先学会在新的开发环境下编译和执行程序。

如果你正在编写的是一个设计文档，那么你的列表应该专注于受众需要学习的信息，而不是要执行的“任务”。例如：

After reading the design spec, the audience will learn the following:

• Three reasons why Zylmon outperforms Zyljeune.
• Five reasons why Zylmon consumed 5.25 engineering years to develop.

为受众量身打造文档

根据受众的需求而写作，需要无私的同理心。你对文档内容的解释，需要满足的是受众的好奇心，而不是你自己的。如何跳出自我，让你的文档去适配受众？不幸的是，并没有简单的答案，只能给你提供一些规范供参考。

词汇和概念

让文档使用的词汇与受众匹配。请参阅Words寻求帮助。

“亲近”你的受众。你团队内的成员可能了解你团队的通用缩写，但是其他团队的人是否了解？当受众范围更大时，你需要做更多说明。

相似的，你软件团队中的老手可能了解团队项目的实现细节以及数据结构，但是其他所有人包括团队新成员都不了解。除非文档本就是为团队中的老手而写，否则你通常必须做比你预期更多的解释。

“知识诅咒”

专家经常遭受“知识诅咒”(the curse of knowledge)。这意味着专家对一个主题懂得越多，反而会让他们对新手更难做解释。作为专家，你很容易忘记新手并不知道你已经知道的内容。新手既不理解会引用到一些微妙交互的解释，也不明白专家不愿意停下来加以解释的复杂系统。

从新手的角度看，“知识诅咒”是由于模块未编译而导致的“File not found”链接错误。

练习

1. 假设下面段落是一篇论文的开头，目标受众为从未编过程的医生。找到段落中遭受“知识诅咒”的部分。

C is a mid-level language, higher than assembly language but lower than Python and Java. The C language provides programmers fine-grained control over all aspects of a program. For example, using the C Standard Library, it is easy to allocate and free blocks of memory. In C, manipulating pointers directly is mundane.

1. 若该段是针对计算机科学专业的本科生，熟悉Python但是刚接触C，它还遭受“知识诅咒”吗？

使用简单词汇

英语已成为全球技术交流的主要语言。然而，相当一部分的技术读者更习惯于英语外的其他语言。因此，请使用简单的词汇而不是复杂词汇，更不要使用过时的词汇或者过于复杂的英语词汇。Sesquipedalian之类的罕见单词会让读者反感。

文化中立及习语

保持你的写作文化中立。不应该让受众在了解软件的工作原理前，还要去了解NASCAR、板球或相扑。如下例句就充满了美国的棒球比喻，就像苹果派一样，会让巴黎的读者摸不着头脑：

If Frambus 5.0 was a solid single, Frambus 6.0 is a stand-up double.

习语指的是整体含义与短语中单个单词字面含义不同的短语。例如，如下短语就是习语：

• a piece of cake
• Bob's your uncle

Cake? Bob? 大多数美国的读者都认可第一句话的含义，而大多数英国读者会知道第二句话的意思。如果你的受众只是英国人，那么Bob's your uncle是OK的。然而，如果你的受众来自全球，请将该习语写成this task is done。

习语在我们日常对话中如此常见，以至于习语的特殊非字面含义，对我们来讲变得不可见。也就是说，习语是另外一种形式的“知识诅咒”。

注意，一些受众可能会使用翻译软件来阅读文档。使用一些特殊文化用语或者习语，比起使用直接简单的英文，会让翻译软件更加“抓狂”。

练习

找出下列句子的问题：

1. As of Version 3.0, it was still kosher to call the Frambus method.
2. Deciding which BlogResource constraints are combinable is a sticky wicket.
3. Be that as it may, you still have to write unit tests.

Reference

原文: https://developers.google.com/tech-writing/one/audience