xml文档规则_避免文档陷阱的7条规则

xml文档规则

在开源社区中，英语是通用语言 。 为了降低翻译成本，许多团队已将英语作为其文档的源语言。 但是令人惊讶的是，为国际读者使用英语写作并不一定会使以英语为母语的人处于更好的位置。 相反，他们往往会忘记文档的语言可能不是听众的母语。

让我们以下面的简单句子为例：“使用foo bar命令加密密码”。 在语法上，这个句子是正确的。 鉴于英语中经常使用“ -ing”形式（gerunds），并且大多数以英语为母语的人都认为它们是表达事物的一种优雅方式，以英语为母语的人通常会毫不犹豫地用这样的句子来表达。 经过仔细检查，该句子是模棱两可的，因为“使用”可以指对象（“密码”）或动词（“加密”）。 因此，可以用两种不同的方式来解释该句子：

• “对使用foo bar命令的密码进行加密。”
• “使用foo bar命令加密密码。”

只要您具有关于该主题的先前知识（密码加密或foo bar命令），就可以解决这种歧义，并正确地确定第二个版本是该句子的预期含义。 但是，如果您缺乏对该主题的深入了解，该怎么办？ 如果您不是专家，而是只有该主题的一般知识的翻译员，该怎么办？ 或者，如果您不是英语母语者，也不熟悉动名词等高级语法形式？

即使是说英语的人也需要培训才能编写清晰直接的技术文档。 第一步是提高对文本的可用性和潜在问题的认识，因此让我们看一下可以帮助避免常见陷阱的七个规则。

1.了解您的目标受众，并步入他们的鞋子。

如果您是为最终用户编写的开发人员，请从他们的角度查看产品。 该结构是否反映了用户的目标？ 角色技术可以帮助您专注于目标受众，并为读者提供适当的详细程度。

2.遵循KISS原则-保持简短和简单。

该原理可以应用于多个级别，例如语法，句子或单词。 以下是示例：

• 使用最简单的适当时态。 例如，当提及一个动作的结果时，使用现在时：
  • “ 点击“确定”。 将出现“打印机选项”对话框。 →→单击“确定”。 出现“打印机选项”对话框。”
• 根据经验，用一个句子提出一个想法； 但是，短句并不是自动易于理解的（特别是如果它们是名词的积累）。 有时，将句子修剪成一定的字数可能会引起歧义。 反过来，这会使句子更难以理解。
• 不常见且冗长的单词会影响阅读速度，可能会成为非母语人士的障碍。 使用更简单的替代方法：
  • “ 利用 ”→“使用”
  • “ 表示 ”→“显示”，“告诉”或“说”
  • “ 先决条件 ”→“要求”

3.避免干扰阅读流程。

将粒子或更长的括号移到句子的开头或结尾：

• “但是，它们没有被标记为已安装。 ”→“但是，它们没有被标记为已安装。”

将长命令放在句子的末尾。 这也可以为自动或半自动翻译提供更好的句子分割。

4.区分两种基本信息类型。

区分描述性信息和基于任务的信息非常有用。 描述性信息的典型示例是命令行参考，而操作方法则是基于任务的信息。 但是，技术写作中需要两种信息类型。 经仔细检查，许多文本包含两种信息类型的混合。 明确区分信息类型将很有帮助。 为了更好地定位，请相应地标记它们。 标题应反映部分的内容和信息类型。 对描述性部分使用“基于名词的标题”（“ Frobnicators的类型”），对基于任务的部分使用口头表达的标题（“ Installing Frobnicators”）。 这可以帮助读者快速确定他们感兴趣的部分，并允许他们跳过当前不需要的部分。

5.考虑不同的阅读情况和文本消费方式。

您的某些读者在转向产品文档时已经感到沮丧，因为他们自己无法实现某个目标。 他们也可能在嘈杂的环境中工作，这使其很难专注于阅读。 另外，不要期望您的听众会翻阅封面，因为许多人使用表，索引或全文搜索来浏览或浏览文本以查找关键字或查找主题。 考虑到这一点，请从不同的角度看待您的文本。 通常，需要折衷找到适合多种情况的文本结构。

6.将复杂的信息分解为较小的块。

这使听众更容易记住和处理信息。 例如，程序不应超过7到10个步骤（根据认知心理学中的米勒定律 ）。 如果需要更多步骤，请将任务分成单独的过程。

7.形式遵循功能。

根据以下问题检查您的文本：某个句子，一个段落或一个部分的目的 （功能）是什么？ 例如，这是一条指令吗？ 结果呢 一个警告？ 有关说明，请使用主动语音：“配置系统”。 被动语音可能适用于以下描述：“系统已自动配置。” 在可能发生危险的步骤或动作之前添加警告。 着眼于目的也有助于检测冗余内容，以帮助消除诸如“基本上”或填料“轻松，”像“ 已有 ”或者“ 全新 ”，或者说是不相关的您的目标受众的任何内容不必要的修改。

您可能已经猜到了，写作就是重写。 好的写作需要努力和实践。 即使您只是偶尔写作，也可以通过关注目标受众并遵循上述规则来显着改善文字质量。 文本的可读性越好，即使对于具有不同语言技能的受众来说，文本也越易于处理。 尤其是在本地化方面，源文本的良好质量很重要：“垃圾进，垃圾出”。 如果原始文本有缺陷，则翻译文本会花费更长的时间，从而导致更高的成本。 在最坏的情况下，翻译过程中的缺陷会成倍增加，并且必须以各种语言进行纠正。

本文基于Tanja在2017年10月24日举行的欧洲开源峰会上的演讲“ 面向国际读者的技术写作 ”。

翻译自: https://opensource.com/article/17/12/7-rules

xml文档规则