防止文档陷阱的 7 条准则

让我们了解一下如何使国外读者更容易理解你的技术文章。

英语是开源社区的通用语言。为了减少翻译成本，很多团队都改成用英语来写他们的文档。 但奇怪的是，为国际读者写英语并不一定就意味着以英语为母语的人就占据更多的优势。 相反， 他们往往忘记了该文档用的语言可能并不是读者的母语。

我们以下面这个简单的句子为例： “Encrypt the password using the foo bar command。”语法上来说，这个句子是正确的。 鉴于动名词的 “-ing” 形式在英语中很常见，大多数的母语人士都认为这是一种优雅的表达方式， 他们通常会很自然的写出这样的句子。 但是仔细观察， 这个句子存在歧义因为 “using” 可能指的宾语（“the password”）也可能指的动词(“encrypt”）。 因此这个句子有两种解读方式:

• “加密使用了 foo bar 命令的密码。”
• “使用命令 foo bar 来加密密码。”

如果你有相关的先验知识（密码加密或者 foo bar 命令），你可以消除这种不确定性并且明白第二种方式才是真正的意思。 但是若你没有足够深入的知识怎么办呢？ 如果你并不是这方面的专家，而只是一个拥有泛泛相关知识的翻译者而已怎么办呢？ 再或者，如果你只是个非母语人士且对像动名词这种高级语法不熟悉怎么办呢？

即使是英语为母语的人也需要经过训练才能写出清晰直接的技术文档。训练的第一步就是提高对文本可用性以及潜在问题的警觉性， 下面让我们来看一下可以帮助避免常见陷阱的 7 条规则。

1、了解你的目标读者并代入其中。

如果你是一名开发者，而写作的对象是最终用户， 那么你需要站在他们的角度来看这个产品。 文档的结构是否反映了用户的目标？ 人格面具persona 技术 能帮你专注于目标受众并为你的读者提供合适层次的细节。

2、遵循 KISS 原则——保持文档简短而简单

这个原则适用于多个层次，从语法，句子到单词。 比如:

• 使用合适的最简单时态。比如， 当提到一个动作的结果时使用现在时:
  • " Click 'OK.' The 'Printer Options' dialog will appear. " -> "Click 'OK.' The 'Printer Options' dialog appears."
• 按经验来说，一个句子表达一个主题；然而， 短句子并不一定就容易理解（尤其当这些句子都是由名词组成时）。 有时， 将句子裁剪过度可能会引起歧义，而反过来太多单词则又难以理解。
• 不常用的以及很长的单词会降低阅读速度，而且可能成为非母语人士的障碍。 使用更简单的替代词语:
  
  • " utilize " -> "use"
  • " indicate " -> "show"，"tell" 或 "say"
  • " prerequisite " -> "requirement"

3、不要干扰阅读流

将虚词和较长的插入语移到句子的首部或者尾部:

• " They are not, however, marked as installed. " -> "However, they are not marked as installed."

将长命令放在句子的末尾可以让自动/半自动的翻译拥有更好的断句。

4、区别对待两种基本的信息类型

描述型信息以及任务导向型信息有必要区分开来。描述型信息的一个典型例子就是命令行参考， 而 HOWTO 则是属于基于任务的信息；（LCTT 译注：HOWTO 文档是 Linux 文档中的一种）然而， 技术写作中都会涉及这两种类型的信息。 仔细观察， 就会发现许多文本都同时包含了两种类型的信息。 然而如果能够清晰地划分这两种类型的信息那必是极好的。 为了更好地区分它们，可以对它们进行分别标记。 标题应该能够反映章节的内容以及信息的类型。 对描述性章节使用基于名词的标题（比如“Types of Frobnicators”），而对基于任务的章节使用口头表达式的标题（例如“Installing Frobnicators”）。 这可以让读者快速定位感兴趣的章节而跳过对他无用的章节。

5、考虑不同的阅读场景和阅读模式

有些读者在阅读产品文档时会由于自己搞不定而感到十分的沮丧。他们在一个嘈杂的环境中工作，也很难专注于阅读。 同时，不要期望你的读者会一页一页的进行阅读，很多人都是快速浏览文本，搜索关键字或者通过表格、索引以及全文搜索的方式来查找主题。 请牢记这一点， 从不同的角度来看待你的文字。 通常需要折中才能找到一种适合多种情况的文本结构。

6、将复杂的信息分成小块

这会让读者更容易记住和吸收信息。例如， 过程不应该超过 7 到 10 个步骤（根据认知心理学中的 米勒法则）。 如果需要更多的步骤， 那么就将任务分拆成不同的过程。

7、形式遵循功能

根据以下问题检查你的文字：某句话/段落/章节的 目的（功能）是什么？比如，它是一个指令呢？还是一个结果呢？还是一个警告呢？如果是指令， 使用主动语气： “Configure the system.” 被动语气可能适合于进行描述： “The system is configured automatically.” 将警告放在危险操作的 前面 。 专注于目的还有助于发现冗余的内容，可以清除类似 “basically” 或者 “easily” 这一类的填充词，类似 “already existing ” 或“ completely new” 这一类的不必要的修饰， 以及任何与你的目标大众无关的内容。

你现在可能已经猜到了，写作就是一个不断重写的过程。 好的写作需要付出努力和练习。 即使你只是偶尔写点东西， 你也可以通过关注目标大众并遵循上述规则来显著地改善你的文字。 文字的可读性越好， 理解就越容易， 这一点对不同语言能力的读者来说都是适合的。 尤其是当进行本地化时， 高质量的原始文本至关重要：“垃圾进， 垃圾出”。 如果原始文本就有缺陷， 翻译所需要的时间就会变长， 从而导致更高的成本。 最坏的情况下， 翻译会导致缺陷成倍增加，需要在不同的语言版本中修正这个缺陷。

---

via: https://opensource.com/article/17/12/7-rules

作者：Tanja Roth 译者：lujun9972 校对：wxy

本文由 LCTT 原创编译，Linux中国 荣誉推出