防止文档陷阱的 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”
