有朋友问,公司决定使用结构化写作的方法来编写公司和设备的文档资料,那应该选择什么文档类型呢?怎样才能够产出有质量的文档?
今天就这个话题,谈谈我的看法。
- 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分别是空客公司和波音公司自己制定的飞行类手册的企业标准。他们现役飞机的飞行类手册都以这两种格式发布。如果你所在的公司接收到这种类型的数据,那么最好还是使用他们定义的文档类型。
不管采用什么文档类型,计算机能保证的是文档符合文档类型的定义。文档类型并不能保证提供完整的、有质量的文档。要提供有质量的文档,还需要文档团队从工程数据、行业经验、写作方法、语言的应用、质量标准等方面下功夫。
国内华为公司的专家分享过技术资料写作方法,北大的高志军老师分享过文档质量评估方面的话题,可以参考。