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

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

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

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

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

做结构化怎样选择文档类型相关推荐

详解非结构化数据（文档）安全管理解决方案
随着互联网技术的日新月异,内容数据逐渐在各行业的业务中占据更重要的地位.日常的业务过程中,需要处理的大量电子文档.图片.音频.视频等,都属于内容数据范畴. 例如,某银行的无人营业网点的远程业务办理中, ...
python文档字符串_结构化的python文档字符串,对IDE友好
在PHP中,我习惯了PHPdoc语法: /** Do something useful @param first Primary data @return int @throws BadExcepti ...
html 的基本结构、标签（分类、关系）、文档类型、页面语言、字符集、语义化
结构代码 <!DOCTYPE html> <html><head> <meta charset="UTF-8"><title& ...
前端：HTML5/36/HTML5简介，文档类型定义，网页字符集，页面结构标记，文章相关的标记，其它标记，音频标记，视频标记，表单中新增的属性，表单input元素type属性的值
HTML5简介 HTML5是新一代的HTML: HTML5目前主要应用在手机端,在PC端最新浏览器已经开始支持了,但还不全面: HTML5是由W3C和WHATWG合作的结果: W3C是万维网联盟,主要 ...
html网页主题结构,常用html元素总结包括基本结构、文档类型、头部、主体等等...
1.基本结构: 复制代码代码如下: 2.文档类型: (1)HTML 4.01 (2)HTML5 (3)XHTML 1.0 复制代码代码如下: 3.头部: (1)字符集复制代码代码如下: (2)引入J ...
文档类型定义和合法性(2)
8.5.3 子元素列表由于SEASON元素被声明为可以接受任何元素作为子元素,因而可以接受各种各样的元素.当遇到那些多多少少有些非结构化的文本,如杂志文章时,这种情况就很有用.这时段落.副栏.项目列 ...
XML之文档类型定义和合法性（转）
来至:liang--liang博客:http://www.cnblogs.com/liang--liang/archive/2008/01/15/1039277.html 好牛 XML被作为一种元标记 ...
DOCTYPE html PUBLIC 指定了 HTML 文档遵循的文档类型定义
DOCTYPE html PUBLIC 指定了 HTML 文档遵循的文档类型定义今天看到一篇CSS应用的一个友好搜索,我按网页上的代码复制.粘贴后预览时总达不到效果,而直接拷贝他的实例却能达到效果, ...
新的 HTML5 文档类型和字符集是,前端面试题--HTML5+CSS3(1)
1.CSS3有哪些新特性? 1. CSS3实现圆角(border-radius),阴影(box-shadow), 2. 对文字加特效(text-shadow.),线性渐变(gradient),旋转(t ...

做结构化怎样选择文档类型