同源开发

date:2018-03-08
author:高志军

什么是同源开发

同源开发的英文是Single Sourcing，字面意义上的理解则是从同一个来源开发生成不同用途的文档。Ament (2002)给出的定义为：

同源开发

“同源开发并非一种技术，而是一种方法论”，其能帮助实现系统性信息复用。在这种方法论的指导下，仅需在数据库或源文档中进行一次模块化内容的开发，就能在多种环境下，根据不同受众、不同需求、不同目的而组合出不同的文档，并实现不同格式的输出，从而实现内容的复用和多渠道发布。

具体而言，同源开发

前言

同源开发是开发可复用的信息的一种方法。本指南以简明的语言和示例来解释如何构建模块化文档，你可以针对不同的受众和目的以不同的格式复用模块化文档。

本指南首先概述了同源开发方法。然后它会引导你完成将线性文档转换为模块化文档的10个步骤过程。 这些步骤通过示例向你展示如何构建内容，配置语言以及利用技术来最大化可用性和可重用性。

为了向你提供同源开发流程的现实情况，本指南中的步骤，指南和示例都非常具体。为了提供一个灵活的框架，你可以为自己的目的复用，这些指南是模块化的。选择你需要的指导方针。然后定制它们以满足你的特定需求。

本指南适用于对同源开发感兴趣的任何人：

  • 想要灵活的框架来成功开发同源文档的技术写作人员和编辑
  • 希望以提高印刷和在线文档质量的同时节省时间和金钱的方式对企业出版物进行标准化的技术出版物经理
  • 想要了解更多关于同源开发的信息，并将它实际用于公司出版环境中的技术传播专业的教师和学生。
  • 即使你没有参与同源开发，本指南也为你提供了改进文档可用性的指导原则。

本指南分为以下章节：

第1章 关于同源开发 解释同源开发是什么，同源开发的原因，同源开发如何运作，同源开发类型以及如何成功实施同源开发。

第2章 构建文档 使用步骤解释了如何将线性文档转换为模块化文档。该过程中的10个步骤中的每一步都与详细的书写准则相互参照。该过程还解释了如何重用你的经验来构建项目风格指南。

第3章 构建内容 解释了如何构建，组装和链接模块化内容。指南解释了如何编写内容模块，如何将模块组织到文档中，以及如何交叉引用文档。

第4章 配置语言 指南解释了如何优化在线文档的语言。指南还解释了如何在开发具有多个作者的文档时保持单一的，以用户为中心的书写风格。

第5章 利用技术 指南解释了如何利用行业标准工具和技术来节省时间和金钱。指南还解释了如何使用这些工具将文档标准自动化。

第1章 关于同源开发

同源开发是一种构建文档的方法，可让你复用你开发的信息。你可以开发模块化内容，然后将该内容组合成不同的格式，例如印刷手册，在线帮助系统甚至网站。复用信息可以节省时间和金钱，因为它消除了重复的工作。

同源开发也增加了文档的可用性。在传统文档中“可以拥有”的可用性标准成为模块化文档中的“必备条件”。实际上，同源开发迫使你为用户做正确的事情。

同源开发是一种方法，而不是技术。尽管与同源开发相关的软件工具很复杂，但它使用模块化写作，而不是技术，最终决定了同源开发项目的成功。为确保成功，开发本地的、基于项目的模块化写作标准。

什么是同源开发？

同源开发是复用信息的一种方法。为了复用信息，同源开发将文档写作过程中的输入与输出分开。 同源开发改变了你开发信息的方式：

  • 复用内容：与基于格式的文档不同，基于内容的文档可以以不同的格式复用。基于格式的文档由于内容与特定格式绑定，因此无法以不同的格式复用。基于内容的开发工具使你能够在元素级别（模块化）而不是文档级别（线性）开发信息。如果你开发的模块化内容与任何给定格式无关，则可以以多种不同格式复用内容。
模块化写作：与线性（基于文档的）写作不同，模块化（基于元素的）写作可以以不同的文档格式复用。线性写作是分层次（基于文档本身的结构）和顺序的（假设给定的阅读顺序）。线性文档几乎不可能复用。模块化写作是非层次化和非顺序的。模块的结构和顺序由不同的文档决定，你可以分别配置和组合。模块化写作包括将内容分块、用标签标记标题和对链接进行交叉引用。
  • 组装文档：与传统桌面出版不同，同源开发组装来自相同内容的不同文档。一旦开发独立的内容模块，就可以将它们组合成不同的文档格式，以满足不同的受众和目的。

同源开发的原因

同源开发节省时间和金钱，提高文档的可用性，并增加团队协同作用。通过在不同文档格式中复用相同内容，可以减少重复工作并提高灵活性。通过开发可用于任何格式的模块化内容，你可以提高各种格式文档的可用性。通过开发共享模块，你可以确保从样式指南到文档模板等各方面的一致决定。

同源开发如何运作

在同源开发中，你可以构建模块化内容，将模块组装到文档中，并将模块链接在一起。你可以构建回答特定问题（人员，时间，地点，原因，方式）的模块化内容（例如主题，过程，定义，图表，表格等）。这些模块即使脱离上下文也很有意义。

你可以将内容模块组织成不同类型的文档（例如，印刷的手册，在线帮助系统，培训手册，网站等）。每个组装的文档都有不同的受众，目的和格式。 你可以构建交叉引用（例如，目录，节内容，内联交叉引用，索引）， 这些交叉引用将给定文档的模块有逻辑地连接起来，并将它们转化为连贯的文档。

同源开发的类型

发布不同文档格式的相同模块化内容，称为同源开发。或者，你可以使用同源开发为重新组装的不同文档类型重新组织模块化内容。

重新调整用途不仅仅是文件转换。它是修改以一种文档格式（例如，印刷手册）开发的信息的过程，以便在转换为其他格式（例如联机帮助）时有意义。重新调整用途的目的是确保不同文档格式的相同内容的可用性。因为这是一个认知过程，重新调整最好由人来完成。 你可能会决定将你的内容模块重新组装为三个不同的文档：面向概念的用户指南，面向任务的在线帮助和面向课堂的培训手册。要重新组装你的内容，你可以使用以下过程：

  • 标记源文件。
  • 自定义转换模板。
  • 重新组装文件。
  • 成功实现同源开发

要成功实现同源开发，请先从小型的现实测试项目开始。将信息架构和信息开发分离。并为模块化写作建立指导方针。当你首次实施同源开发时，可以为小型现实项目设定适度的目标，这些项目有真实的交付物和项目截止日期。小型项目让你能在安全范围内测试，小步骤让你保持清醒，现实项目让你保持诚实。

设立同源开发团队时，让团队成员尽其所能。集中信息架构，分散信息开发，并鼓励多多交流。模块化写作，而不是编程，最终决定同源开发项目的成败。在开始同源开发项目之前，建立模块化写作的统一指导。根据过去的成功经验指导方针。在实现目标的同时，以新的成功经验更新准则。

第2章 建立文档

同源开发远不止对文档进行机械的组装。模块化写作真正推动同源开发流程。模块化写作是一种认知过程。你评估内容，将其分解成最小的可能模块，按内容类型标记模块，将模块配置为有意义的层次结构，并将层次结构链接到相关的层次结构。

本章将分10步介绍如何将线性文档转换为模块化文档。这些步骤与第3章“构建内容”和第4章“配置语言”中的详细指南和示例相互参照。本章中的步骤构成了可修改的通用过程，而不是你必须遵循的特定过程。

本章旨在帮助你在包含线性文档的传统环境中开始同源开发。本章假设你已经继承了一个线性文档，你希望将其转换为同源开发的模块化文档。实际上，它向你展示了如何将你的线性文档转换成同源开发的模式

本章包含以下步骤：

#. 识别模块 识别组成现有线性文档的主要和次要模块。大多数文档都由主要模块组成，包括定义列表，术语表，步骤，过程，主题和故障排除方案。次要模块包括示例，图形，分项列表，备注和表格等。 #. 标记模块 使用明确标识模块内容以及如何呈现内容的语法标记每个模块。为主模块构建标题。例如，当标记定义列表时，使用一致的标题语法来区分不同类型的定义。使用图片标题，小标题或图标标记辅助模块。例如，标注数字时，请从系统或用户角度描述其内容的标题。 #. 组织模块 在你的同源开发文档中，将次要模块集成到主要模块中。然后按类型分隔主模块。对于逐项列表，你可以将逐项列表添加到定义列表，步骤，过程，节内容，主题和故障排除方案中。对于你在构建同源文档过程中使用的所有术语，为这些术语的定义构建术语表。（例如，在主题中使用的术语） #. 构建模块 在同源文档中构建每个模块。构建的模块应保持一致。遵循构建每种模块类型的指导原则。构建主要模块，如构建定义列表，将它们格式化为定义列表，而不是表格。尽可能使用平行结构。至于构建次要模块，如在构建提示模块时，确保提示和建议提供肯定的建议。确保注意事项和警告在构建提示模块时提供负面建议。 #. 编辑模块 编辑模块以确保你的同源开发是干净利落的。使用可以在任何情况下使用的清晰，简洁和一致的语言。你应该验证模块标签，并确保小标题和图片标题写得很清楚。在验证模块组织时，应确保主模块和次要模块组织正确。在验证模块语言时，应确保模块中的语言在任何情况下均有效，其中包括缩写，大小写，平行结构，人员，句子结构，时态和语态。 #. 组织文件 将主要模块组织到文档层次结构中。你可以按字母，受众，细节，重要性，位置，顺序和类型组织主要模块。然后将层次结构明晰化以将信息带到表面。此过程旨在优化文档的节内容和从属内容，你可以提升节内容或从属内容的层次。 #. 交叉引用文档 通过构建目录，节内容，内联交叉引用和索引来交叉引用文档。使用电子超链接设置预先格式化的样式，可以在打印和在线文档中复用（重新生成）。 #. 转换文件 将源模板映射到目标模板。文档转换是将文档从一种格式转换为另一种格式的机械过程。在你可以转换文档之前，你需要为不同的格式构建模板，将源模板映射到目标模板。然后自动生成新的文档格式。你可以将文档转换为多种不同的文档格式，例如打印的手册，在线帮助，培训材料和网站。要将文档从一种格式转换为另一种格式，请遵循以下过程：构建源模板，构建目标模板，将源模板映射到目标模板并生成目标文档。 #. 测试文档 测试你生成的每个打印或在线文档的可用性。测试文档，而不是测试人员或开发方法。在文档编辑中，密切关注文档组织结构和交叉引用。在可用性测试中，关注结果，而不是开发方法。纠正你发现的所有问题。编辑文档时，请验证其组织结构和交叉引用。纠正所有与文档相关的问题。从内部和外部测试文档的可访问性和有用性。 #. 制定指南 制定协商一致的书面指南。指南建立在开发，编辑和测试过程中发现问题及解决办法上。你可以从上到下或从下到上制定撰写指南。自下而上的指导方针更适合于同源开发项目，因为它们完全基于实际项目中的作用，而不是理论项目中应该起作用的项目。撰写指南能强化团队在同源开发项目中的协同作用，也是一个周期性的过程，具有不同的阶段，包括提议，批准，编译，分发和执行。对每一个同源开发项目重复这个过程。

第3章 构建内容

模块化写作驱动同源开发流程。如果你开发的模块化内容在任何情况下都有意义，你可以针对不同的受众和目的以不同的格式复用它。

本章详细说明如何构建模块化内容。它解释了如何开发主要模块（例如程序和主题）和次要模块（例如图表和表格）。它解释了如何在同源文档中组织主要模块和次要模块，然后将它们重新组织为输出文档的打印格式和在线格式。它解释了如何在组装模块之间建立“认知桥梁”（例如，目录，部分内容，交叉引用和索引）。虽然每个指导方针已经在成功的同源开发项目中得到证明，但并非每一个指导方针都适合于每个项目。选择你需要的指导方针。然后修改它们以符合你的公司和项目要求。

标题

标题是图形和表格的标题。在给标题编号时，可以使用绝对（文档）或相对编号（章节或附录）。从系统角度（例如，标题以名词开头）或用户角度（例如，标题以动词开头）描述图形。仅从系统角度描述表格（例如，标题以名词开始）。

交叉引用

交叉引用链接组成文档的模块。在印刷文档中，在交叉参考中包含页码。用户通过转到指定的页面找到参考信息。在在线文档中，交叉引用使用超链接表示。用户通过单击超链接访问引用的信息。要开发在印刷和在线文档中有效的交叉引用，请设置预先格式化的样式和电子超链接。预格式化样式确保你的交叉引用具有一致的语法。实际上，你可以在用于开发文档的软件中编写准则。电子超链接使你能够将交叉引用转换为不同的印刷和在线格式。电子交叉引用还自动更新目录，节内容，内联交叉引用和索引。

定义列表

定义列表定义产品组件和相关技术。组件包括硬件（例如，CPU，显示器，打印机等）和软件（例如菜单项，命令，变量等）。它们通常在独立定义列表中进行描述。术语包括专有术语（例如，网络节点管理器）或公共领域术语（例如，文件传输协议）。技术术语通常包含在术语表中。为了最大限度地提高复用性，将术语和定义格式化为定义列表，而不是表格。定义列表使用文本格式将术语与其定义配对。定义列表的一个典型例子是词汇表，它看起来像一本词典。由于这些列表不会将内容绑定到特定的输出格式，因此它们很容易以不同的格式复用。定义表格使用表格列将术语与其定义配对。表格将内容与特定格式绑定。因此，表格很难以不同格式复用。在引入定义列表时，使用标准的措词。定义列表中的术语应与文档中的呈现形式完全一致。如果组件包含子组件（例如，如果菜单项包含子项），则将子组件“嵌套”在其“父”组件下。为便于参考，请按字母顺序排列词条，除非有令人信服的理由不要改变顺序（例如，逻辑上我们习惯将“是”放在“否”之前）。在定义中使用平行结构。用名词或动词而不是冠词开始列表定义。使用同义词定义该术语，并在整个定义中使用同义词。如果定义包含序列项目，请将项目转换为分项列表。

例子

例子是说明文字的单词和短语。与简单的例子不同，复杂的例子太大而不能出现在句子中。用圆括号分隔简单的例子。圆括号在规则和这些规则的举例之间提供了清晰的视觉区分。如果这些例子是完整句子，则将它们格式化为单独的句子。用分段符分隔复杂的例子。不要嵌套示例。也就是说，不要在示例中包含示例。虽然合乎逻辑，但这样的嵌套对用户来说很难遵循。你可以将示例集成到主要模块（例如，定义列表，过程，过程，主题和故障排除方案）和次要模块（例如分项列表和备注）中。

图形

图形是图像或图表。图像是可以在文档中引用的逼真图形（例如，软件程序的屏幕截图）。图表是可以用线条，箭头，圆形，正方形等绘制的抽象图形（例如条形图，饼图，流程图等）。组合图像和图表的一种常见方式是用文本和箭头注释屏幕截图。在介绍数字时，请使用标准措辞和电子交叉引用。在打印版中使用图像编号作引用，在联机版中使用图像标题作引用。从同源开发构建打印和联机文档时，优化打印图像，然后将其转换为在线格式。对于打印查看，以可接受的打印分辨率以TIFF（标记图像文件格式）格式保存图像。如果可能，请将图像保存为全彩色，以便将其转换为任何联机格式。在线观看时，请以网页浏览器分辨率以GIF（图形交换格式）或JPEG（联合图像专家组）格式保存图像。 GIF格式最适合包含文本的图像（例如截图）。 JPEG格式最适合不包含文字的图像（例如照片）。为了最大限度地提高复用性，请引用图像而不是将它们复制到文档中。然后你可以使用文档转换程序将图像自动转换为其他格式。

首页内容

首页内容是正文内容开始之前出现在书本前面的材料。虽然首页内容的撰写起源于平面媒体，但它与在线媒体有着相似之处。你可以以在线格式从打印格式重新组装首页内容，反之亦然。

无论格式如何，首页内容都与特定的输出文档相关联，而不与同源输入模块相关。要在印刷版和在线文档中重新调整首页内容，请考虑在两种媒介中使用相同模块的方法。重新组装首页内容可以使用条件文本标记某个文档类型的某些部分，而使用其他部分标记其他类型的文档。

词汇表

词汇表解释文档中的技术术语，其中包括专有术语（主要）和公有领域术语（次要）。就术语而言，使用缩写而不是全拼写。在他们的定义开始处说明缩写。用名词或动词而不是冠词开始定义。不要使用术语来定义自己。用同义词定义该术语，并在整个定义中使用同义词。开发主术语表以增加一致性并消除冗余。主术语表（外部使用和内部使用）使用户能够找到许多不同文档中的技术术语的定义。它们还使你能够消除术语和定义中的冗余和不一致。编译主词汇表是一个循环过程，包括组织，编辑和更新。

标题

标题是文档部分的标题。在标题中，尽可能直接回答具体问题。使用表明模块类型和内容的标题语法。例如，在标记词汇表分区时，对符号字符使用“符号”，对数字字符使用“数字”。在字母标签中，不要使用多个字符。忽略缺少的字母字符。确保标题在脱离语境时可以理解。

索引

索引是按字母顺序排列的交叉引用列表，可帮助用户快速找到信息。无论你是为打印文档，在线文档还是两者设置索引格式，建立索引条目最好不要超过三个级别。超过三个等级的索引条目难以在打印文档中使用，并且几乎不可能在联机文档中使用。尽可能嵌套索引条目。如果两个或更多索引条目以相同的第一个词或短语开头，请将条目嵌套在该常用词或短语下。将打印或在线格式的索引条目格式化。如果是为打印版，包括开始和结束范围。对于联机版，仅包含启开始范围。使用文档转换程序将打印格式转换为在线格式，反之亦然。为了帮助用户在文档集中查找信息，构建主索引。主索引是由相关文档共享的索引。主索引使用户能够跨文档集找到答案。主索引还使你能够消除文档集中的冗余和不一致。

分项列表

分项列表垂直显示序列项目以便于扫描。你可以构建简单的逐项列表（不包含子列表或注释）或复杂的逐项列表（包括子列表，注释或两者）。该列表可以包括标题，注释和其他列表。对分项列表中的所有项目使用平行结构。例如，用动词或名词开始所有项目。同样，如果一个列表项目形成完整的句子，则为列表中的所有项目添加句点。格式化列表项时，建立列表样式。强调主要项目。用连续词或短语将长句转换为列表。

备注

备注是补充其他模块的小文本块。这些文本块包含肯定或否定的建议。对于肯定的建议，请使用提示或建议。对于否定建议，请使用注意或警告。这样的建议出现在给定的模块中，并对该模块发表评论。该建议通常突出显示一个框或一个图标来吸引注意力。

大多数产品文档包含四种不同类型的备注。请使用适用于特殊情况的澄清说明或符合重要要点的说明。使用肯定建议的提示可帮助用户应用模块中描述的信息以满足其特定需求。对于特定操作可能导致数据丢失，数据损坏，安全问题或性能问题时使用注意。针对特定操作可能导致用户身体伤害或者可能导致硬件损坏时使用警告。

组织结构

文档组织驱动文档组装。将内容模块组织到针对特定受众，目的和格式的文档中。在同源输入文档中组织模块化内容时，将次要模块集成到主模块中。然后按类型分隔主模块。在组织（组装）输出文档时，使用逻辑层次结构来定位特定的受众和目的。你可以按字母顺序，受众类型，详细程度，重要程度，物理位置，连续顺序或模块类型来组织文档部分和子部分。你也可以将这些组织策略结合起来。例如，你可以对过程（类型）进行分组，按照逻辑顺序（时间）对其进行排序，将子过程与其父级过程（详细信息）分组，并首先引入安装和卸载过程（重要性）。然后展平层次结构以将信息提取到输出文档的表面。这包括将章节或附录提升到节内容或将子节内容提升到节内容。

步骤

步骤是解释如何执行操作的分步说明。有四种类型的步骤：单步步骤，多步步骤，超步骤和子步骤。无论类型如何，请以标准措辞介绍所有步骤。从步骤的目标开始介绍。以指出分步步骤而结束。使用冒号标注步骤介绍（:) 。使用分步步骤强调用户操作和选项。要强调单步步骤，请使用分项列表。为了强调步骤中的子步骤，使用子列表显示每个子步骤。在有大量文本的长步骤之间，以粗体或斜体类型突出步骤。在子步骤中，提供分项列表便于可选操作。以清晰的视觉和文字指示开始可选步骤（例如“可选：”），表明这些步骤不是强制性的。

流程

流程回答了一个问题：“如何？”因为答案是顺序的，所以它们通常被格式化为有序列表。像主题一样，过程是描述性的，而不是必要的。他们解释某人或某事做了什么（陈述），而不是用户应该做什么（祈使）。在撰写叙述性流程时，使用主动语态和现在时。只要有可能，就将流程组织成连续的小步骤。在步骤中，强调步骤和选项。将流程步骤和这些步骤的详细信息分开。根据需要包含分项列表或子步骤。

章节内容

章节内容是介绍小节的列表。这些列表是为了列出文档的目录。目录汇总了文件结构。章节内容总结章节结构。章节内容在在线文档中尤为重要，在这些文档中，通过将文档章节超链接到其子章节来补充主要导航系统。尽管节内容可以以多种不同格式显示，但最常见的格式是分项列表。对于包含小节的章节，使用逐项列表而不是句子。对于长而大的章节（例如章节或附录），添加注释来描述每个子章节包含的内容。要复用印刷和在线文档的章节内容，请使用电子交叉引用。

表格

表格是在较小的可视空间中比较相关信息的列和行的集合。通过比文字或图形更简洁地呈现信息，表格可以进行一目了然的比较。在可以使用列表的地方避免使用表格。也就是说，不要将定义列表，分项列表，过程或过程格式化为表格。在引入表格时，使用标准的措辞和电子交叉引用。在打印文档中，使用表格编号而不是标题进行交叉引用。如果表格出现在与交叉引用不同的页面上，请在交叉引用中包含页码。在线文件中，表格标题通常没有编号，则交叉引用表格标题。为了消除多余的表格单元，组合冗余的行和列。通过组合冗余行，你可以在表格中构建可视化层次结构。你可以将表格整合到主题中。通常，不要将表格添加到其他类型的主模块（例如，过程）。

目录

目录列出了组成文件的模块。列出所有序言和介绍，而不是内容。清楚地列出章节和附录部分（仅限部分）或完整性（章节和小节）。列出术语表和索引等。通过组合冗余列，你可以在目录内建立“子表”。在目录中，你可以为用户提供文档的摘要或详细视图。每种方法都有其优点和缺点。选择与你的文档的受众，目的和格式相匹配的详细程度。

主题

主题是描述是谁，做了什么，什么时候，在哪里或为什么的文本。要回答这些问题，你可以使用参数，描述，说明或叙述。在大多数产品文档中，大部分主题都是描述。为了让你的答案清晰明了，请按重要程度和细节排列句子和段落。直接与用户交谈，以主动语态，第二人称和现在时态写出主题。

故障排除方案

故障排除方案是主题和步骤的混合体。通过总结一个问题（主题）及其解决方案（步骤）介绍方案。然后分别详细解释问题和解决方案。在描述问题时，重点关注问题，而不是问题的原因。将解决方案格式化为步骤。将步骤格式化为有序列表。将选项格式化为分项列表。将密切相关的问题和解决方案组合到一起。在方案中分离每个不同的子问题和子解决方案。使用一致的子标题语法将子问题映射到子解决方案（例如，“问题X”和“解决方案X”）。

第4章 配置语言

你可以“配置”语言来增加文档的可用性。如果你的语言“默认”是以用户为中心的，那么你的写作会产生易于使用的文档。例如，如果你使用主动语态，第二人称和现在时态写作，则你的口吻是直接与用户交谈。同样，如果你在标题，标题，列表项目等中使用平行结构，则可以让用户更轻松地扫读文档以获取所需信息。最后，如果你写简洁的句子，你可以为用户提供他们可以理解的信息块，而不用多加思考。

你还可以配置语言以提高文档的复用性。如果你遵循默认书写风格构建共享模块，则可以将模块无缝集成到许多不同的文档中。尽管缩写，大小写和标点符号不一致对文件的可用性来说并不致命，但它是非专业的体现。你可以使用默认的语言配置向用户显示文档，这些文档看起来似乎仅由一位作者撰写的。

为了补充内部风格指南，本章介绍了可帮助提高同源开发文档的可用性和复用性的语言指南。并非每个指南都适合每个项目。选择你需要的指导方针。然后修改它们以符合你的公司和项目要求。

缩略语

缩略语是缩写形式的单词和短语。为了使用户能够在任何地方识别缩写，首次在模块中提及它们时将其拼出。使用通用缩写和商标缩写。避免不常用的缩写。用户通常更加熟悉通用缩写（例如，“HTML”）而不是缩略语代表的词（例如“HyperText Markup Language”）。为了使通用的缩写更易被理解，在主要模块中第一次提到缩写时将缩写展开。商标缩写（例如“IBM”）是法定缩写产品或公司的名称（例如“International Business Machines, Inc.”）。使用商标缩写而不是缩写词。不常用的缩写（例如“UMB”）对于用户来说通常比他们缩写的单词更不熟悉（例如，“upper memory block”）。出于这个原因，你应该在你使用它们的地方拼写出罕见的缩写。

大写

英文字符应遵循一致大写格式并应用于文档标题，图片标题，命令，定义列表，文件名，术语表和分项列表中。有四种方法可以将单词大写。大写通常用于文字字符串，例如计算机命令和文件名（例如“AUTOEXEC.BAT”）。小写字母通常用于词汇表术语（例如，“database”）。初始（标题）大小写通常用于产品元素，例如计算机程序名称和菜单项（例如“Print Preview”）。缩写（句子）大小写通常用于图片标题，小标题和列表（例如，“About this guide”）。

平行结构

对具有相同功能的元素使用相同的语法结构。通过使用相同的结构，你可以表达类似元素之间的相同的观念。在图片标题，术语表，小标题，索引，介绍，列表，步骤，句子和表格中使用平行结构。

人称

人称是人称代词的形式，代词可以代表说话人（第一人称），说话对象（第二人称）还是说出的人或事物（第三人称）。以第二人称单数来称呼你的主要受众（例如系统管理员）。以第三人称复数（例如，系统操作员）处理你的次要听众。？？

标点

使用标点符号可以使你的写作不仅在语法上是正确的，而且在任何情况下都易于理解。使用逗号，连字符，圆括号和句点将文本分解为容易在线理解的小块。避免冒号和分号。冒号（:）增加句子长度，并降低文本可用性，尤其是在线文本。要缩短句子，请使用句号而不是冒号。逗号将句子分解成容易理解的块。为了缩短句子，使用尽可能多的逗号，如果语法上允许的话。括号在报表和这些报表的例子之间提供了清晰的视觉区分。在句子中，使用括号而不是逗号分隔简单的例子。分号（;）增加句子长度，并降低可用性，尤其是在线文本。要缩短句子，请使用句点而不是分号。

句子结构

为在线文档准备模块，应缩短和简化句子。为了简化句子，请使用主动语态和现在时态。将长句分成短句以增加可用性。将长序列短语分成单独的句子。如有必要，可以用“和”，“或”，或“然后”开始其中一些句子。对于连续词组，使用平行结构。如果一个句子包含许多序列项目，则将这些项目转换为分项列表。

时态

用户实时查看文档。“现在”是用户目前所在的任何地方。要建立以用户为中心的模块，尽可能使用现在时。仅在涉及当前短语或句子之前或之后发生的事情时，使用过去式或将来式。

语态

要清楚直接地向用户说话，用主动语态而不是被动语态来撰写句子和短语。

第5章 利用技术

你可以利用技术来自动化同源开发流程的许多部分。例如，你可以使用条件文本来控制同源文档中的哪些内容模块以什么样的输出文档的格式，语言和版本显示。同样，你可以对你希望更改的文本使用变量（例如，产品名称或版本）。

本章为你提供了用于构建同源文档的创作工具，转换工具和内容管理系统（CMS）的概述。它还为使用这些工具的重要功能（例如条件文本，搜索引擎和可变文本）提供了指导。最后，本章将向你展示如何在为多语言用户构建复杂文档时利用这些功能来节省时间和金钱。

虽然每个指导方针已经在成功的同源开发项目中得到证明，但并非每一个指导方针都适合于每个项目。选择你需要的指导方针。然后修改它们以适合你的项目。

条件文本

条件文本是许多创作和转换工具中的一项功能。此功能可让你有条件的显示标记元素，然后打开或关闭这些元素。例如，你可以仅仅为获取联机帮助标记文档的某些部分，然后在打印文档之前将其关闭。对特定文档类型，格式，语言和版本使用条件文本。如果导致重复工作，请避免使用条件文本。例如，不要使用条件文本解决具有两种不同格式的两个文档索引之间的冲突。你可以格式化条件文本，以便在创作工具中轻松查看。根据你的创作工具，你可以使用颜色或字符样式来标识不同的条件文本标签。无论你如何格式化条件文本，确保标记不干扰输出格式。例如，如果你将蓝色用于印刷手册中使用的条件文本，则手册可能无法正确打印。你可以将条件文本标签用于各种用途。如果你在同源文档中发现自己使用了10个或更多条件文本标签，请考虑使用内容管理系统（CMS）。

惯例

惯例是你在给定文档中遵循的印刷规则。要构建可在任何地方实现的文档惯例，请勿硬编码字符格式。使用基于内容的创作工具，使用元素标签设置约定。然后，你可以使用转换工具将约定转换为其他文档格式。使用基于格式的创作工具，设置带有字符样式的约定。例如，如果你使用的是Adobe FrameMaker，则可以为系统消息定义一个等宽字体样式。同样，你可以为用户输入定义粗体等宽字体样式。

开发工具

同源开发工具是文档驱动或数据库驱动的。最好的开发工具基于SGML或XML，两者都将格式与内容分开。尽管市场上有许多不同的同源开发工具，但大部分都属于以下三类之一：编写工具用于开发文档。通常，它们是桌面出版应用，你可以使用它们开发同源的多媒介文档（例如，Adobe FrameMaker）。评估创作工具时，请查找它是否有符合产业标准的功能，包括条件文本，交叉引用，大型文档，页面布局，文字处理等。转换工具将文档从一种格式自动转换为另一种格式，他们将打印文档转换为在线格式（例如，Quadralay WebWorks Publisher）。许多是用于和桌面出版应用共同工作。评估转换工具时，请查找是否有符合行业标准的功能，如自动转换，条件文本，交叉引用，大型文档，多种文档格式和页面布局。内容管理系统（CMS）用于管理大量的同源开发内容。通常，它们是数据库驱动的工具，它按元素对信息进行编目，而不仅仅是文档（例如，Arbortext Epic Editor和Documentum）。在评估内容管理系统时，请查看行业标准功能，包括分类，搜索，安全，版本控制和工作流程。

文件名

直观的文件名在大型同源开发项目中非常重要。输入文件名（手动）应指示模块内容和类型。只要有可能，请在文件名中使用文档标题（例如章节标题）。输出文件名（自动）应指示模块内容和类型。

本地化

本地化涉及文件翻译和对当地市场的定制。对自定义元素使用条件文本。将文档从一种语言翻译成另一种语言。例如，你可以用英文撰写文件，然后聘请外部机构将文件翻译成日文。在三种翻译方法中，机器翻译（自动）和翻译记忆（半自动）最适合同源开发。与同源开发一样，这些翻译方法消除了重复的工作。定制文档内容以匹配所记录产品的本地版本。例如，产品的英文和日文软件包可能有不同的文件名。尽管文档本地化对用户有益，但它也增加了信息开发任务的复杂性。幸运的是，在本地化文档时，同源开发可为你节省大量时间和金钱。实际上，进行本地化的成本本身就是使用同源开发的理由。

搜索引擎

搜索引擎使用户能够按标题，页眉信息，文本和索引搜索文档。为了最大限度地提高搜索引擎的效率，整合搜索和索引功能。

变量

变量是动态文本的定义。大部分授权收费都有系统和用户变量。你可以将这两种变量组合起来构建非常复杂的变量。例如，你可以设置一个运行页眉信息的变量，以自动重复章节标题，而标题又包含变量中定义的产品名称。当你希望改变文字时创建变量。大多数用于构建同源文档的创作和转换工具使你能够创建变量，如果你预期要改变文本的话。为每个变量创建一个名称和一个定义。然后在文档中插入变量而不是文本。确保变量名对于任何作者都易于找到、易于理解。当你更改变量定义时，文档中所有出现的变量都会使用新定义进行更新。

参考资料