转到结构化写作后的几点变化

或许是随着公司产品越来越多，公司的手册越来越复杂，用户越来越难找到需要的信息；或许是因为公司管理手册的使用者不满足于长篇大论的文字，希望能够获得只跟他相关的政策、程序等信息。

总之，公司决定从MS Word、非结构化FrameMaker或者Markdown转向基于XML的结构化写作。但XML是另一个世界，它到底是什么样子？和之前的方法相比有什么不同？

1

XML是什么？

XML是eXtenable Markup Language（可扩展标记语言）的缩写。它是一种允许用户根据业务需求，对自己的标记语言进行定义的语言。

我们可能不一定听说过XML，但很可能听说过它的兄弟 - HTML。HTML被设计来在浏览器呈现内容，现在它在我们的电脑和手机里无处不在，比如：浏览器里，微信里，淘宝里，今日头条里。大家常说的H5就是第5代HTML的标准。HTML中定义了固定的标签来标识不同的意思：<h1>表示一级标题，<p>代表段落，由浏览器来把它显示给用户。与HTML相比，XML的不同在于：它没有定义任何固定的标签，是由使用它的的人来定义标签，同时是使用的人来决定怎么使用这些标签。它是一个工具、一种机制。

根据不同的使用场景，人们使用XML定义了很多文档标准，其中包括：

• DITA

  达尔文信息类型体系结构，用于创作、生成和交付面向主题的信息类型内容，适用于产品手册、管理手册、业务文档等通用型文档。

• S1000D

  技术出版物生产的国际规范，其用途包括：国防系统-包括陆海空产品， 民用航空产品，建筑业产品，船舶工业产品。

  S1000D标准规范最初是由欧洲航空器材制造商协会制定，该协会现改名为欧洲航空航天防务工程协会ASD(Aerospace and Defence Association of Europe)。随后，美国航天工业协会AIA（American Aerospace Industry Association）和美国航空运输协会ATA(Air Transport Association of America)也加入了合作制定的行列。

• ATA 2300

  航空飞行类手册国际标准。

• DocBook

  非常适合于关于计算机硬件和软件的书籍和论文（虽然它绝不限于这些应用），它由OASIS 的DocBook 技术委员会维护。

2

几点变化

1. 内容和样式分离

当从文字处理或类似的工具转向使用XML进行结构化创作时，最显著的区别是样式从内容中分离出去了。

以前，需要在编写内容时根据预期的输出调整格式。可以手动调整字体样式、大小或边距。MS Word提供所见即所得的功能，在屏幕上马上可以看到输出的效果。 

现在，XML将内容与输出样式完全分离。内容保存在XML文件中，直到创建输出时，样式才会应用。在发布之前，内容是用未格式化的XML编写的。根据编辑器的不同，可能只看到元素标记和文本。这允许写作者将注意力集中在内容编写本身，而不用关心样式。还允许通过多个样式将相同的内容创建多个输出（PDF、HTML等）。

2. 内容一致性

公司的编写指南可能会说，所有图片标题都居中，放在图片下方，斜体。然而，写作者甲觉得他更喜欢图片上方加粗体的标题。通过手动操作，写作者甲可以按照他想要的格式调整。这样就会出现不同的写作者写的内容不一致。但是XML会改变这种情况。

XML不允许编写者自由发挥地写作，而是定义了一系列的规则。这个规则定义在文档类型(DocType)中。文档类型定义了哪个元素可以出现在哪里，出现几个。样式表则决定这个元素输出成什么样子。在XML中，写作者甲只能将一个图片标题元素放置在指定的位置，样式表将它置于图片下方的中心并设置为斜体。

XML仍然有一定的灵活性，但在很大程度上，它确保了相同的内容以相同的方式出现在相同的位置。使用XML进行写作时，编辑软件根据DocType中定义的规则确保所有写作者写的内容的一致性。

3. 手册被拆分成小块

在MS Word中，可能所有内容放在一个文件中。如果一个人在编辑这个文件，那么这个文件就会被锁定，其他人不能同时进行编辑。或者可能会冒创建多个冲突版本的风险。

使用XML编写手册，绝大多数情况是将手册分解成若干部分。手册由一个结构文件（在DITA中叫做Map，在S1000D中叫做PublicationModule）和与之连接的内容小块（DITA中叫Topic，S1000D中叫DataModule）组成。

当写作者更改或编写内容时，将使用最小的XML内容块。这不仅让大家可以同时写一本手册，还有利于内容的重用。

4. 内容重用

如果你的100本手册中都有公司简介。因为某种原因需要更新公司简介信息（比如：你们公司与另一家公司合并并更名了）。是否必须打开所有100本手册并修改其中的公司简介100遍呢？这个问题在XML中不存在。

使用XML，由于公司简介将在其自己的XML内容块中编写，该内容块存储在所有写作者都可以使用的内容管理系统中，因此100本手册中的每一本都有一个指向这个公司简介的引用。只需要更新这一个文件，每当你打开并发布100本手册时，它们都会自动拉取更新的公司简介。

内容重用可以在多个级别上实现。可以保持它的简单性，只使用完整的内容块文件。还可以创建实体来重用整个短语或单词。但是，重用粒度越细，管理难度会加大。

5. 个性化文档

在我们编写产品操作手册时，有些产品基本一样，但是有少许不同。这种情况下，我们为这些产品编写一本手册，然后针对不同的地方，做如下处理：

如果是产品A，则这样操作：
XXX
XXX
如果是产品B, 则这样操作：
YYY
YYY

如果是产品A，则这样操作：XXXXXX如果是产品B, 则这样操作：YYYYYY

由手册的使用者来判断到底应该遵循哪个步骤。但这在某些情况下不能满足要求，比如：用于飞机出现故障需要飞行员快速行动的场景（QRH）。

使用XML文档以后，我们还是这样写：

<sect product="产品A">
<p>XXX</p>
<p>XXX</p>
</sect>
<sect product="产品B">
<p>YYY</p>
<p>YYY</p>
</sect>

但在输出的时候，我们可以给程序传入"生成针对产品A的手册"的指令，得到的输出就是针对产品A的手册。适用产品B的内容被过滤掉或者灰色显示表示不适用。