英语是开源社区的通用语。为了降低翻译成本，许多团队已将英语切换为文档的源语言。但令人惊讶的是，为国际受众用英语写作并不一定使以英语为母语的人处于更有利的地位。相反，他们往往会忘记文档的语言可能不是受众的第一语言。
让我们看一个简单的句子作为例子：“使用 foo bar 命令加密密码。” 从语法上讲，这个句子是正确的。鉴于“-ing”形式（动名词）在英语中经常使用，并且大多数母语人士认为它们是表达事物的优雅方式，因此母语人士通常会毫不犹豫地像这样措辞造句。但仔细检查后，该句子是模棱两可的，因为“using”可能指的是宾语（“密码”）或动词（“加密”）。因此，该句子可以解释为两种不同的方式
- “加密使用
foo bar命令的密码。” - “通过使用
foo bar命令加密密码。”
只要您对主题（密码加密或 foo bar 命令）有先前的了解，您就可以消除这种歧义，并正确判断第二个版本是该句子的预期含义。但是，如果您缺乏对该主题的深入了解怎么办？如果您不是专家，而是一位只对该主题有一般知识的翻译人员怎么办？或者，如果您是以英语为非母语的人，不熟悉像动名词这样的高级语法形式怎么办？
即使是以英语为母语的人也需要接受培训，才能编写清晰明了的技术文档。第一步是提高对文本可用性和潜在问题的认识，因此让我们看看可以帮助避免常见陷阱的七条规则。
1. 了解您的目标受众并设身处地为他们着想。
如果您是为最终用户编写文档的开发人员，请从他们的角度看待产品。结构是否反映了用户的目标？人物角色技术可以帮助您专注于目标受众，并为您的读者提供适当的详细程度。
2. 遵循 KISS 原则——保持简短和简单。
该原则可以应用于多个层面，例如语法、句子或单词。以下是一些示例
- 使用最合适的简单时态。例如，在提及动作的结果时使用现在时
- “
单击“确定”。将出现“打印机选项”对话框。” → “单击“确定”。“打印机选项”对话框出现。”
- “
- 根据经验，一个句子表达一个想法；但是，短句并不一定容易理解（尤其是当它们是名词的堆积时）。有时，将句子缩减到一定的字数可能会引入歧义。反过来，这使得句子更难理解。
- 不常见和长单词会减慢阅读速度，并且可能是非母语人士的障碍。使用更简单的替代方案
- “
utilize” → “use” - “
indicate” → “show”、“tell”或“say” - “
prerequisite” → “requirement”
- “
3. 避免干扰阅读流畅性。
将小品词或较长的括号移到句子的开头或结尾
- “
但是，它们未标记为已安装。” → “但是，它们未标记为已安装。”
将长命令放在句子的末尾。这也使得句子的分割更适合自动或半自动翻译。
4. 区分两种基本信息类型。
区分描述性信息和基于任务的信息非常有用。描述性信息的典型示例是命令行参考，而操作指南是基于任务的信息；但是，技术写作中需要这两种信息类型。仔细检查后，许多文本都包含两种信息类型的混合。明确区分信息类型很有帮助。为了更好地定位，请相应地标记它们。标题应反映节的内容和信息类型。描述性章节使用基于名词的标题（“Frobnicators 的类型”），基于任务的章节使用动词性标题（“安装 Frobnicators”）。这有助于读者快速识别他们感兴趣的章节，并允许他们跳过他们目前不需要的章节。
5. 考虑不同的阅读情境和文本消费模式。
当您的某些读者求助于产品文档时，他们已经感到沮丧，因为他们无法自行实现某个目标。他们也可能在嘈杂的环境中工作，这使得他们难以集中精力阅读。此外，不要期望您的受众会从头到尾阅读，因为很多人会浏览文本以查找关键字，或者使用表格、索引或全文搜索来查找主题。考虑到这一点，从不同的角度看待您的文本。通常，需要做出妥协才能找到适用于多种情况的文本结构。
6. 将复杂信息分解为更小的块。
这使受众更容易记住和处理信息。例如，程序不应超过 7 到 10 个步骤（根据认知心理学中的米勒定律）。如果需要更多步骤，请将任务拆分为单独的程序。
7. 形式服从功能。
根据以下问题检查您的文本：某个句子、段落或章节的目的（功能）是什么？例如，它是指令吗？结果？警告？对于指令，请使用主动语态：“配置系统。”被动语态可能适用于描述：“系统已自动配置。”在危险发生之前的步骤或操作之前添加警告。关注目的也有助于检测冗余内容，以帮助消除诸如“基本上”或“容易地”之类的填充词，诸如“已经存在”或“完全新的”之类的不必要的修饰，或任何与您的目标受众无关的内容。
正如您现在可能猜到的那样，写作就是重写。好的写作需要努力和实践。即使您只是偶尔写作，您也可以通过关注目标受众并遵循上述规则来显着改进您的文本。文本的可读性越好，即使对于语言技能各异的受众，也越容易处理。特别是当涉及到本地化时，源文本的良好质量非常重要：“垃圾进，垃圾出。” 如果原始文本存在缺陷，则翻译文本需要更长的时间，从而导致更高的成本。在最坏的情况下，缺陷会在翻译过程中成倍增加，并且必须在各种语言中进行纠正。
本文基于 Tanja 在 2017 年 10 月 24 日欧洲开源峰会上所做的题为“面向国际受众的技术写作”的演讲。
2 条评论