线性文档转换为模块文档的十步法

今年7月的内容管理与智能交付专题培训中，Ziegler教授在讲授内容模块化时，提到了Kurt Ament写的 Single Sourcing: Building Modular Documentation（同源化：构建模块文档）书中构建模块化文档的10步过程。

single_sourcing_building_modular_documentation

Kurt Ament是一位信息架构师，在印刷文档和在线文档方面拥有丰富的经验，曾服务于惠普公司、休斯飞机公司、赛门铁克公司和施乐公司等主要公司。HP OpenView 业务部门在全球范围使用由他开发的WebWorks Publisher模板，将FrameMaker+SGML文档转换为在线帮助系统。除了Single Sourcing: Building Modular Documentation, Kurt 还写了 Indexing: a Nuts-and-Bolts Guide for Technical Writers。

Kurt在第二章 “构建文档”中解释了将线性文档转化为模块文档的过程：

识别模块
标记模块
组织模块
构建模块
编辑模块
组织文档
交叉引用文档
转换文档
测试文档
制定指南

下文系对原书章节的翻译和摘抄，欢迎大家指正。关于构建文档的更多信息，请参阅原著。

步骤一：识别模块

将现有的线性文档转换模块文档前，需要标识组成文档的部件或模块。

大部分的文档由主要模块组成。主要模块包括：

定义列表描述了产品组件和技术。
词汇表是解释文档模块中使用的技术术语的定义列表。
步骤解释了如何逐步执行顺序任务。
流程描述由人或事物执行的顺序任务。
主题通过论证、描述、阐述或叙述回答何人、何事、何时、何地或何原因。
故障排除方案解释故障（主题）与故障的解决办法（步骤）。

主要模块由辅助模块组成：

示例是说明文本的单词或短语。简短的示例出现在文本中。长的示例可以独立存在。
图表是说明文本的图像或图表。图像和图表通常是外部开发的，然后在文档中引用。
条目清单垂直显示顺序排列的项目，便于快速阅读。列表可以是简单的或复杂的，并且可以包括标题和注释。
注释说明是补充其他模块的小文本块。这些文本块可以包含正面或负面信息。
表格是用于比较狭小视觉空间中相关信息的列和行的集合。

步骤二：标记模块

使用语法标记文档中的模块，语法可以清晰标识模块内容，以及如何呈现内容。

为主要模块构建标题，例如：

标记定义列表时，使用一致的标题语法区别不同类型的定义。
标记词汇分类时，分开字母和数字字符。不要将字符进行归类。忽略丢失的字符。
标记步骤时，用动词回答“如何”的问题。区分超级步骤和其他步骤。
标记流程时，用动词回答“如何”的问题。使用动名词而不是动词。
标记主题时，回答具体的问题。使用区分不同类型主题的一致语法。
标记故障排除方案时，描述故障而不是解决方案。从用户的角度描述故障。

使用说明文字、标题或图标来标记辅助模块，例如：

大多数示例没有标签。如果示例本身构成独立的部分或子部分，请添加描述性标题。
标记图表时，使用从系统角度或用户角度描述图表内容的说明文字。
标记条目清单时，使用一致且可预测的标题语法来区分不同类型的信息。
标记注释时，使用区分肯定建议（注释和提示）和否定建议（注意和警告）的词语。
标记表格时，仅使用从系统角度描述其内容的说明文字。

对集成到主要模块中的辅助模块（例如，条目清单），使用其自有的标题进行标记，这个做法可能看起来很奇怪，但准确的标签可以更轻松地组织模块。

步骤三：组织模块

在同源文档中，将辅助模块集成到主模块中。然后按类型分隔主模块。

将辅助模块集成到主要模块中，例如：

可以向定义列表、条目清单、步骤、流程、主题和故障排除方案添加示例。
可以向主题添加图表。如果可能的话，不在其他类型的主要模块中添加图表。
可以向定义列表、条目清单、步骤、流程、章节目录、主题和故障排除方案添加条目清单。
可以在定义列表、步骤、流程、主题和故障排除方案中添加注释、提示、注意和警告。
可以在主题中添加表格。如果可能的话，不在其他类型的主要模块中添加表格。

将主要模块分成不同的部分，例如：

为所有的定义列表构建一个部分。定义列表解释了产品组件和技术（例如，菜单项做了什么）。
为单源文档中使用的技术术语的所有定义（例如，主题中使用的术语）构建词汇表。
为所有步骤构建一个部分。步骤说明用户如何执行操作（例如，如何打印文档）。
为所有流程构建一个部分。流程说明产品如何执行特定操作（例如，将XML内容模块转换为HTML文档），或用户如何执行更一般的操作（例如，诊断问题）。
为所有主题构建一个章节。主题描述了何人、何事、何时、何地或为何（例如，产品的目的）。
为故障排除方案构建一个部分。故障排除方案描述故障并解释如何解决故障（例如，如果应用程序无法启动该怎么办）。

在基于打印的单源文档中，可以将步骤、过程和主题组织到单独的章节中。同样，可以将定义列表和故障排除方案分组到附录中。

通过将主要模块分隔到单源文档的不同部分，构建一个“数据库”，并在组织文档时重复使用这个数据库。 为了便于在单源文档中查找信息，按字母顺序对每章或附录中的模块进行排序。如果标题清楚地指明了模块内容和类型，则按字母顺序排列的单源文档可能实际上建议了组织文档的方法。

步骤四：构建模块

在单源文档中构建每个模块。遵循每个模块类型的指南，一致地组织模块。

构建主要模块：

构建定义时，将定义格式化为定义列表，而不是表格。尽可能使用并行结构。
在构建词汇表条目时，使用缩写而不是拼写。切勿使用术语来定义自己。
构建步骤时，使用标准措辞。组织步骤，以强调用户操作和选项。
构建流程时，将步骤格式化为有序列表项。
构建主题时，按重要性和细节级别排列内容。使用主动语态，第二人称和现在时。
构建故障排除方案时，分开故障和解决方案。主题用于故障。步骤用于解决方案。

如果是将线性文档转成模块文档，重新构建（或模块化）内容，而不是重新构建模块内容。

构建辅助模块：

使用括号格式化简单示例。使用段落格式化复杂示例。不要在示例中包含示例。
如果要从单一来源构建打印和在线文档，需要优化要打印的图像，然后将其转换为在线格式。为了最大限度地提高可重用性，需要通过引用将图像嵌入到文档中。
为了最大化可用性和可重用性，对逐项清单中的所有项使用平行结构。
确保注释和提示提供积极的建议，注意和警告提供负面建议。
可以使用列表的地方就避免使用表格。介绍表格时，使用标准措辞和电子交叉引用。合并冗余的行和列，以消除冗余表格单元。

步骤五：编辑模块

在将输入模块组织到输出文档之前，编辑输入模块以确保单源“数据库”在任何上下文中都适用。这种前期编辑消除了对组合内容的冗余编辑。

审核模块标签

确保按如下规则编写标题和说明文字：

确保标题尽可能直接回答特定问题。确保脱离背景时标题仍然有意义。
从系统角度或用户角度描述图表。仅从系统角度描述表格。

审核模块结构

确保恰当地组织主要模块和辅助模块。

确保将每种类型的主模块组织到单源文档的不同部分。
确保每个辅助模块正确集成到主模块中。

审核模块语言

确保模块中的语言在任何上下文中都有效。

在模块中第一次提及时拼写出缩写。使用常用缩写，但不是很少见的缩写。
使用一致的规则大写文档标题、说明文字、命令、定义列表、文件名、词汇表和条目清单。
使用平行结构，使模块更容易快速阅读。
使用第二人称单数直接与用户交谈。
缩短和简化句子。如果句子包含许多序列项，将序列项格式化为条目清单。
使用现在时维护模块中以用户为中心的时间。
使用主动语态，以提高模块的清晰度。

步骤六：组织文档

根据特定受众、目的和格式，将主要模块组织到文档部分和子部分中，然后使文档结构扁平化，将信息带到表面并提高可用性。

构建文档层次结构

要构建文档部分和子部分，通过以下方法中的任何一种来组织主模块。

按标题的字母顺序组织主要模块。例如，按字母顺序排列程序和定义列表以便于参考。
按用户类型组织模块。例如，将新手和专家的部分分开。
按详细程度组织模块。例如，在解释特定产品功能之前介绍一般产品功能。
按重要性级别组织模块。例如，在其他步骤之前列出安装和卸载的步骤。
通过所描述的对象的物理位置来组织模块。例如，根据用户界面上出现的位置，从左到右，从上到下，介绍程序的部件。
按顺序组织模块。例如，在配置步骤之前包括安装步骤。
按类型组织模块。将主要模块分成不同的部分。例如，将主题和步骤分开。

细化文档层次结构

复杂的层次结构可以帮助写作人员理解复杂的产品。但复杂的层次结构实际上可能会阻碍用户使用这些相同的产品。这种可用性问题在在线文档中尤其严重。在线文档未能为用户提供足够的可视空间来查看复杂的层次结构。

通过以下方法中的任何一种来使层次结构扁平化，以便细化文档部分和子部分。

简化层次结构的简单方法是提倡使用章节。例如，要简化具有许多不同标题级别的章节，将每个部分（第一级标题）转换为章节。实际上是将一个复杂的层次结构转换为许多简单的层次结构。
简化层次结构的另一种方法是提倡使用子节，这种方法比第一种方法复杂些。例如，如果要简化具有许多不同标题级别的章节，但不能将部分转换为章节，将每个子部分（第二级标题）转换为一个部分（第一级标题）。

步骤七：交叉引用文档

通过构建目录、章节目录、内联交叉引用和索引来交叉引用文档。

构建目录

目录将组成文档的主要模块按逻辑顺序链接。无论其格式如何，所有文档都需要显示文档结构的目录表。构建一个目录，为用户提供文档的摘要视图或详细视图。包括章节和附录，以及它们的小节。参考词汇表和索引。

构建章节目录

章节目录是介绍其子部分的列表。这些列表在在线文档中尤为重要，它们将文档章节链接到其子节。在包含子节的每个章节中，构建带注释的目录。该目录可以是包含子节标题、简要描述、被引用子节的页码或超链接的列表。

构建内联交叉引用

内联交叉引用将文档中的相关模块相互链接。在打印文档中，交叉引用通常包括页码。在线文档中的交叉引用不包括页码。从模块向相关模块添加内联交叉引用（例如，从步骤到定义列表，反之亦然）。设置预先格式化的样式和电子超链接，可以在不同的打印和在线格式中重复使用。

构建索引

索引是按字母顺序排列的交叉引用列表，使用户能够快速定位信息。这些列表显示主题、步骤、定义等之间的关系。为文档构建综合索引。构建不超过三个级别的索引条目。如果可能，使用索引工具，动态标记模块和常规索引，然后自动将生成的索引转换为不同的格式。

步骤八：转换文档

文档转换是将文档从一种格式转换为另一种格式的机械过程。在转换文档之前，需要为不同格式构建模板，然后将模板相互映射。构建和映射模板后，可以自动生成不同格式的新文档。

文档格式的类型

可以将文档转换为多种不同的格式：

印刷手册：设计用于打印的文档（例如，用户指南，参考手册等）。这些文件可以是书籍或可打印的电子书。
在线帮助：以任意数量的不同在线帮助格式设计的文档（例如，Microsoft HTML Help，Microsoft WinHelp，Oracle JavaHelp，Sun JavaHelp等）。这些文档可以是上下文相关的帮助文档或在线文档。
培训材料：为现场或非现场培训课程设计的文档（例如：幻灯片，工作手册等）。这些文档可以以不同的打印格式和在线格式显示。
网站：基于HTML的文档在互联网上显示为网页。不应将这些文档与基于HTML的在线文档混淆，后者由用户在本地查看的网页组成。

这些文档格式不会更改模块化内容，只是确定模块的呈现顺序和格式。

将文档转换为另一种格式

要将文档从一种格式转换为另一种格式，需要遵循以下过程。

构建源模板
使用文档开发工具（例如，Adobe FrameMaker + SGML）为单源文档构建模板。确保使用特殊功能（例如，条件文本）来准备单源文档的内容，以便转换为其他格式（例如，从打印手册到在线帮助系统）。
构建目标模板
为要从单源文档生成的第二个文档构建模板。
1) 在第二个文档的本机环境中构建原型模板（例如，Microsoft HTML Help）。
2) 使用文档转换工具（例如，Quadralay WebWorks Publisher）构建转换模板。
将源模板与目标模板进行映射
将源模板中的元素（例如，SGML元素）映射到目标模板中的元素（例如，HTML标记）。
生成目标文档
使用文档转换工具（例如，WebWorks Publisher）生成目标文档（例如，HTML帮助）。

步骤九：测试文档

测试组装的每个文档。在文档编辑中，密切关注文档结构和交叉引用。在可用性测试中，关注结果，而不是开发方法。纠正发现的所有问题。

编辑文档

编辑文档时，需要验证文档的结构和交叉引用。纠正文档相关的所有问题。

验证文档结构。确保文档的结构能够突出显示关键信息，并且易于理解。
验证文档中的交叉引用。确保文档以易于使用的方式完全交叉引用。用交叉引用替换冗余信息。

测试文档可用性

从内部和外部测试文档的可访问性和实用性。

测试人员类型

根据可用的资源，从内部或外部测试文档。

要求内部用户（例如，同事）测试文档。从非产品团队中选择测试人员。
要求外部用户（例如，产品验收测试人员）测试文档。选择熟悉该产品的测试人员。

测试类型

测试每个输出文档的可用性。

可访问性：如果用户找不到信息，则信息无用。测试用户是否可以找到他们需要的信息。用户使用文档来解决具体问题。然后仔细观察，看看他们是否能找到所需的信息。
实用性：如果信息没有回答用户问题，则信息无用。一旦用户找到信息，仔细观察他们是否可以使用这些信息来解决提供的问题。

确保将可用性结果整合到写作指南中。

步骤十：制定指南

根据在开发、编辑和可用性测试周期中发现的问题和解决方案，制定协商一致的编写指南。可以自上而下或自下而上制定写作指南。 自下而上的指导方针更适合同源项目，因为它们完全基于实际项目中的工作，而不是理论项目中的工作。一致的书写指南加强了同源项目中的团队协作。

制定自上而下的编写指南

可以为整个公司制定文档标准。企业风格指南通常由委员会制定。 该委员会根据普遍接受的学术标准（例如，芝加哥风格手册）和普遍接受的行业标准（例如，大型软件制造商发布的企业风格指南）制定指南。 委员会将章节草案分发给一个由出版物管理人员组成的小组委员会。如果大多数出版经理批准指南草案，它们将在全公司范围内出版，并成为写作人员和编辑参考的标准。

制定自下而上的编写指南

可以为特定项目制定编写指南。项目风格指南通常由已分配给项目的编辑人员开发。 编辑人员根据项目模块或文档的当前编辑开发了指南。 该指南是编辑人员和作者之间连续协议的摘要。随着项目的进展，指南也在扩展。项目完成后，编辑人员和作者召开会议，讨论项目中哪些有效，哪些无效。然后，编辑人员将“成功案例”编辑成正式的项目风格指南，以便在未来的项目中重复使用。

制定一致的编写指南

在同源项目中，一致的写作指南非常有效。由于可重复使用的内容是基本的项目要求，因此整个团队都非常积极地遵循用于共享信息的共享准则。大家都希望内容模块互相啮合，而不是冲突。

制定协商一致的写作指南是一个具有不同阶段的周期性过程，在所有的同源项目中可以重复这个过程。阶段包括：

提议
根据编辑、可用性测试结果和来自不同作者的想法提出编写指南草案。确保包含否定和肯定的例子。
评审
要求团队成员对每个提议的指南进行投票。给团队成员一个合理的时间（例如，两周）来审查指南。明确表示没有响应计为批准。
汇编
汇编项目样式指南，其中仅包含团队中每个成员审核的指南。一致同意确保每个团队成员将来都遵循这些准则。
分发
将审核的风格指南分发给团队的每个成员。确保将副本发送到其他出版物团体以及公司风格指南的协调员。
执行
在未来的项目中，授权编辑人员执行指南。鼓励作者和编辑人员提出新的指南。