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,它还遭受“知识诅咒”吗?
点击展开答案
  1. 这个段落深受“知识诅咒”。目标受众从未做过编程,所以以下术语对他们不熟悉或者不恰当:
  • language
  • mid-level language
  • assembly language
  • Python
  • Java
  • program
  • C Standard Library
  • allocate and free blocks of memory
  • pointers
  1. 尽管受众是计算机专业类的研究生,这一段同样遭受“知识诅咒”。Python的程序员一般来讲是不知道指针和内存操作的。更好的介绍性段落中,可以增加C语言和Python的比较和对比。

使用简单词汇

英语已成为全球技术交流的主要语言。然而,相当一部分的技术读者更习惯于英语外的其他语言。因此,请使用简单的词汇而不是复杂词汇,更不要使用过时的词汇或者过于复杂的英语词汇。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.
点击展开答案
  1. 犹太洁食(kosher)在世界一些地方已经成为俚语,代表“可接受的用法”。但是更多的人会奇怪,宗教饮食法跟软件有什么关系?
  2. sticky wicket是英国俚语,并没有被广泛使用。请将其替换成challenging problem
  3. Be that as it may是俚语,把它改成However即可。

Reference

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

Copyright @ Lambert 2022 all right reserved,powered by GitbookModified Time: 2024-02-24 14:20:10

results matching ""

    No results matching ""