恩智浦：将开发文档迁移到DITA/XML

摘要：本文是德国同行Parson公司写的一篇文章，描述芯片巨头恩智浦编写文档方法如何从MS Word和Adobe Frame Maker转向基于DITA的结构化写作和发布。英文原文地址：https://www.parson-europe.com/en/references/nxp

- 1 -

项目目标

在开发产品时，恩智浦开发团队会生成大量的内部和外部文档。通常，这些文档是递增的、相互关联的。文档作者经常复制文档并对其进行修改。这样，他们创建了文档的多份拷贝。

恩智浦的所有产品都经历了漫长的开发和生命周期。因此，恩智浦需要并行编写和维护新产品和旧产品的版本以及不同产品开发阶段的文档。此外，产品系列的各个版本的文档在很大程度上是相同的。出于这些原因，恩智浦的身份识别部门（Identification department）希望从根本上改善其文档流程。他们决定转向基于XML的文档，这将使他们能够专业地重用内容，并创建来自单一来源（Single Source）的文档的多种变体（variants）。

恩智浦的文档由软件工程师、技术人员和文档工程师编写、更新和重用。新的文档创作系统应提供易于处理、统一的信息和文档结构以及文档模板，使所有用户快速适应新的文档流程。

恩智浦打算在其所有部门引入基于XML的文档，并将身份识别部门的这次改革作为一个开创性的项目。由于新的文件流程必须符合总体文件战略和IT架构，身份识别部门与埃因霍温总部的中央文件部门密切协调项目的进展。

- 2 -

途径和方法

我们一步一步地引进了新的文档技术和信息架构。首先，我们增强了FrameMaker技术并启用了变体管理（variant management）。这样，我们可以最好地支持所有正在进行的文档任务。

译者注：不同型号的产品文档大体相似但又不完全一样，变体管理用于从一个DITA手册生成不同型号的手册。

为了在XML的基础上创建文档，我们引入了Oxygen的XML编辑器，并开发了一个基于DITA的标准化文档创作系统。这包括：

基于DITA，自定义文档类型
在Oxygen中配置创作支持
自定义Oxygen中的PDF发布
创建内容模型以实现最佳内容重用
创建存储和文件夹结构，以实现最佳的内容重用以及从连接系统导入/导出文件
从Word或FrameMaker迁移现有内容
链接来自外部工具的数据

- 3 -

基于DITA，自定义文档类型

恩智浦使用自定义DITA文档类型，该文档类型定义由中央文档部门维护，并在全公司范围内使用。到目前为止，该文档类型定义主要用于创建面向客户的产品文档。当身份识别部门开始使用Oxygen编写内部开发人员文档时，很明显结构定义并没有涵盖此信息类型的所有要求。我们与恩智浦团队一起评估了DITA文档类型定义，收集了变更请求，并与中央文档部门进行了讨论。这些变化主要集中在额外的XML元素和元数据的定义上，以加强信息产品和内容模块的管理。

基于DITA，具有自定义的附加元数据

- 4 -

Oxygen中的创作支持

Oxygen提供了所谓的框架（Framework）来存储定制的结构定义。框架存储全局设置，并使其可供作者共同使用。对于恩智浦，我们创建了一个自定义框架。现在，只需两步，作者就可以设置Oxygen并根据相同的全局设置进行编写。

为了简化作者的写作过程，我们对框架进行了如下调整：

自动文档类型定义集成（用于离线工作）
插入常用元素的自定义操作（工具栏）
简单填写变量管理的属性
CSS定制（元数据和NXP布局表单）
使用主题方案图在全公司范围内标准化应用元数据（分类）
点击鼠标即可转换PDF

- 5 -

自动生成PDF

Oxygen为作者提供了DITA文档类型定义的集成框架。这包括DITA Open Toolkit（DITA OT），一个从DITA/XML文件创建不同格式输出的插件。由于恩智浦希望在项目的第一阶段专注于PDF输出，我们将现有的自动PDF生成调整为扩展的XML结构定义。现在，作者只需一个命令即可在NXP布局中创建PDF文档。

为此，我们必须修改创建XSL FO文件的DITA OT的XSL脚本。我们必须考虑两件事：恩智浦的排版布局指南和作者对内部文档的特殊要求。目前，PDF文档是由Oxygen的Apache FOP处理器从XSL FO文件创建的。将来，Antenna House发布引擎将用于创建PDF文档。恩智浦中央文档部门目前正在评估此解决方案。

- 6 -

用于重用和标准化的信息架构

恩智浦曾使用Microsoft Word和Adobe FrameMaker编写文档。这两种工具都有各种文档的模板。这些模板定义了文档的章节结构。在改用XML之前，我们对现有文档（信息产品）进行了模块化，并开发了一个可重用的内容模型。通过这种方式，我们创建了新的文本模块（信息对象），恩智浦现在可以在不同的文档中使用这些模块。

我们与负责的恩智浦集团合作，为不同类型的文档（例如架构文档）开发了标准化模板。这些模板确保所有基于XML的文档都符合定义的章节结构。

新的信息架构保证了所有作者都可以重用内容并创建标准化的内容和文档。

- 7 -

与外部系统集成

恩智浦集团使用不同的工具来输入和更新信息。文档所需的大量信息来自外部来源（如需求管理软件DOORS）。恩智浦希望将外部来源的信息集成到文档中，并将其作为Oxygen中的只读文本模块提供。为了实现外部模块的集成，我们为模块定义了相应的DITA/XML结构。

要与外部源交换内容，需要使用脚本和其他工具。