有朋友问，公司决定使用结构化写作的方法来编写公司和设备的文档资料，那应该选择什么文档类型呢？怎样才能够产出有质量的文档？

今天就这个话题，谈谈我的看法。

- 1 -

什么是文档类型

在结构化写作中，文档类型(Document Type)定义了文档的规则。有了这个文档规则，计算机就能验证我们每一个文档是否符合规则，确保文档的一致性。

我们以一个放假通知为例子，说明什么是文档类型。示例通知如下：

如果我们要将所有节日的放假进行结构化，那么通知的规则是这样的：

有且只有一个标题，上例为：中秋节放假通知
有且只有一个称呼，上例为：致亲爱的新老客户
正文中有1个或者多个段落
有且只有一个落款，上例为：@车队管家

如果某个放假通知没有称呼，那么计算机验证的时候就会告诉我们，那不是一个有效的放假通知。

我们写任何文档/手册，不论是用MS Word、FrameMaker、Sphinx、Markdown或者XML来写， 其实都是有一定的规则的。只是有些时候没有把规则明显地写出来，区别在于：不写出来（如MS Word），就不能使用计算机来验证文档的有效性，只能用肉眼看；写出来（像结构化写作这样），计算机就能帮我们验证文档是否符合规则。 

就算使用结构化的方法来写作，现在已经有了很多的文档类型，比如：DocBook、DITA、ATA 2200、ATA 2300、S1000D、Airbus FlightOp、Boeing FTID等等。（对不起，目前都是老外定义的，期待有朝一日中国也能制定文档类型并让全世界用）。

到底我们应该如何选择文档类型呢？

- 2 -

文档类型的分类

按照文档类型的设计思路，分为：1）自顶向下的类型，2）基于内容块的类型。

1）自顶向下的类型

结构化写作，最初和传统写书一样，采用自顶向下的思路，也就是先定义文档整体框架（章节），然后在框架中填写内容。比如：

1 安全要求
    1.1 一般安全摘要
    1.2 安全通告和符号
    1.3 保养和清洁
2 文档概述
    2.1 说明
    2.2 概述
3 常规检查
    3.1 检查项目
    3.2 检查步骤

 采用这种思路的文档类型有DocBook、ATA 2200、Boeing FTID。

采用这种文档类型的价值是：1）保证文档的一致性。不管有多少人写内容，出来的结果就像一个人写的一样。2）单一数据源，多渠道发布。一份手册内容可以一键发布成PDF、HTML、MS Help等输出。3）个性化输出（内容过滤）。根据发布参数，动态过滤内容。

2）基于内容块的类型

随着时间推移，人们发现用户在使用手册的时候大多数不是从第一页看到最后一页。而是根据需要，查看某一部分。比如：工程师对设备进行更换零件时，只需要看具体的某一块内容。

所以人们对方法进行了改进，发明了基于内容块写作的方法。和自顶向下的方法不同，这种方法的思路是将内容块作为最小单元，这个内容块的内容不依赖其他内容块（或者说上下文） ，可以单独使用。然后，将很多内容块组合成一个文档/一本手册。这就满足了上例中工程师更换零件场景的需求。 

使用这种思路设计的文档类型有：DITA、S1000D、ATA 2300。

除了依然具有第一种类型提到的3种价值外，这种类型提供的另外一个工具就是内容重用。内容重用很大程度地减少了重复内容，从而减少维护工作量、翻译工作量、以及避免漏改造成的内容不一致。

按照内容的类型，分为：1）通用型，2）专用型。

1）通用型

这种文档的内容中以标题、段落、列表、表格、图、备注、粗体、斜体等这些通用的类型组成。并无（或者说很少有）具有特殊语义的内容。适合编写各种行业（如：软件、机械设备）的说明书。

属于这种类型的文档类型有：DocBook、DITA。

2）专用型

除了标题、段落、列表、表格、图这些通用类型内容，还包括特殊语义的类型，比如：程序、性能、签派、维修步骤、操作/结果、零件件号。这些类型跟具体的场景相关，具有特殊而具体的语义。

下边的文档类型属于专用型：

• ATA 2200：飞机维修类手册

• S1000D：海、陆、空设备维修手册

• ATA 2300：飞机飞行类手册

• Airbus FlightOps: 空客飞机飞行类手册 （企业标准）

• Boeing FTID：波音飞机飞行类手册（企业标准）

注：DITA是一个特殊的存在，它的核心提供通用的内容类型，但是提供了扩展机制（叫做Specialization - 专有化）来加入专用型的内容。

- 3 -

如何选择文档类型

我们来看看Adobe做的一个"什么文档类型受欢迎“的调查：

（数据来自2018年Adobe的调查，根据787个反馈统计）

调研结果显示DITA最受欢迎，其次是自定义的文档类型。ATA、S1000D和DocBook也因其历史或者清晰的应用领域而上榜。

如何选择：

1）什么时候采用S1000D

S1000D已经非常清晰地表明了它适用的领域：

翻译成中文，它适用的领域是：

• 国防系统 - 包括海、陆、空装备。

• 民用航空产品。

• 基建行业产品 （但我在S1000D规范中没有看到这个行业的特殊需求）。

• 船舶工业产品。

如果你要为以上行业的零部件和设备编写维修类手册，那么应该采用S1000D。

如果不是这些行业，那么就尽量不采用S1000D了。因为：

• S1000D相对复杂。

• 系统建设和维护的成本高。

• 发展慢。S1000D已经发展了30年了，规范的推进主要是由各国的各大制造商的代表参与，相互协调讨论形成一致意见费时费力。

注意：这并不意味着这些行业的所有手册都要使用S1000D，比如：公司管理手册就不应该用S1000D来编写。

2）什么时候采用DITA

如果你要编写的内容以通用内容为主，或者不在S1000D描述的行业，那么可以采用DITA。如果需要，可以在DITA的基础上通过专有化机制来加入自己的需求。

从成本考虑，现在支持DITA编辑和发布的工具很多，使用标准的DITA能够用合理的价格提供漂亮的输出。如果在DITA基础上做专有化，那么会有开发、维护和以后升级版本的成本。这也是为什么有些企业宁愿牺牲一些功能也不做专有化的原因。

如果在你的内容中，没有内容重用，也可以考虑使用DocBook。 

3）什么时候采用ATA 2200, Airbus FlightOps, Boeing FTID

这三个都是航空业手册的文档标准。

ATA 2200是存在很长时间的飞机维修类手册结构化国际标准，现在已经不再开发下一代，后续版本的需求融入了S1000D。新型号的飞机也采用S1000D标准编写和发布维修手册了。如果你所在公司还从飞机厂家那里接收ATA 2200的格式的维修类手册，那么还是建议在公司建立能兼容ATA 2200格式的系统。 

Airbus FlightOps和Boeing FTID分别是空客公司和波音公司自己制定的飞行类手册的企业标准。他们现役飞机的飞行类手册都以这两种格式发布。如果你所在的公司接收到这种类型的数据，那么最好还是使用他们定义的文档类型。

不管采用什么文档类型，计算机能保证的是文档符合文档类型的定义。文档类型并不能保证提供完整的、有质量的文档。要提供有质量的文档，还需要文档团队从工程数据、行业经验、写作方法、语言的应用、质量标准等方面下功夫。

国内华为公司的专家分享过技术资料写作方法，北大的高志军老师分享过文档质量评估方面的话题，可以参考。