在年初的 tcworld 中国大会上，我做了一场题为《道阻且长：在高端装备制造业中实现技术文档高质量交付的实践与思考》的演讲。
在那次演讲中，我以一个欧美地铁列车项目为例，详细介绍了高端装备制造业中技术文档的交付要求和交付流程，并且还分享了项目中遇到的难点和痛点：
- 必须按照客户的要求（合同条款）编制，可回旋的余地很小。
- 内容的专业性特别强，对供应商手册进行内容整合的难度很大。
- 项目周期特别长，进度难以把控，管理难度大。
针对这些问题，虽然我进行过很多思考，但都不足以从根本上解决问题。
最近，我有机会和一位航空航天方面的同行聊了聊 S1000D，并借机向他了解了一下 S1000D 在轨道交通行业的应用情况。
实际上，我在演讲中提到的这些难点和痛点，也同样困扰着那些在国际市场上声名显赫的轨道交通装备制造商们。
早在 2013 年，法国轨道交通装备制造商阿尔斯通 (ALSTOM)、加拿大交通运输设备制造商庞巴迪 (Bombardier) 和法国国营铁路公司 (SNCF) 就曾联合成立了一个指导委员会和工作组。
他们希望能像海运业一样，基于 S1000D 制定出一套行业通用的数据交换协议 (RailDex)，使运营商（铁路公司、地铁公司等）、制造商和供应商可以遵循统一的规范来编制手册及其相关文档，以最大限度地减少各方在信息互通互用方面的成本。
海运业中通用的数据交换协议叫 Shipdex，首版发布于 2008 年。
Shipdex 使船东、造船厂、修船厂、船级社等都使用统一的规范编写手册及相关文档，以最大限度地减少各方在信息互通互用方面的成本。
虽然 RailDex 后来非常遗憾地无疾而终了，但 S1000D 在轨道交通行业仍然是备受青睐的技术文档编制规范。只是大家在具体实施的时候各自为政罢了，不像航空航天和海运业那样在整个行业内实现了大一统。
航空航天、船舶工程以及轨道交通装备都是以产品复杂度高、专业性强和产品使用寿命长而著称的行业。为什么这些行业都对 S1000D 青睐有加? S1000 到底有何独特之处?
本文将从一个技术文档工程师的角度细说原委，希望能为那些对 S1000D 持观望态度的同行和企业提供更进一步的依据和勇气，也为那些没有机会实施 S1000D 但正面临相似困境的小伙伴们提供一些理念上的借鉴和参考。
管理模式
在软件开发中，有两种开发方式经常被放在一起比较：敏捷开发和瀑布模型。敏捷开发通常是时尚、迅捷的代表，而瀑布模型往往以老旧、雍肿的“慢半拍”形象陪衬。
但瀑布模型却和 S1000D 是一对儿管理搭子。S1000D 是起源于航空航天业的技术文档编制和管理规范，后来逐渐扩散到国防工业、船舶工程、轨道交通等行业。
这些行业和航空航天业类似，都属于产品复杂度高、专业性强、产品使用寿命长的行业。在这些行业里，产品的研制都有非常规范、成熟的流程，属于典型的瀑布式研发。
在如此典型的瀑布式研发环境里，产品手册的编制自然也需要按照瀑布模型来进行。
产品手册中需要涵盖的内容范围和深度，一般在项目初期就会确定下来，通常是按照客户要求或者合同条款来确定。
产品手册的编写进度、验证计划和交付时间也需要配合产品的研发节点来安排。比如民用飞机的首飞、试飞取证、首架飞机交付和批生产，地铁列车的样车交付和量产车交付等。
为了契合这些行业中瀑布式研发的需求，S1000D 规范不仅定义了基于模块化和结构化的手册编写方法，还使用业务规则、信息集和数据模块需求清单等方式来指导和规范内容规划阶段的工作。
协同范围
由于产品复杂度高、专业性强，飞机、邮轮、火车或地铁列车等产品的手册编写和维护不只需要多人协作，还需要多家公司协作。
除了制造商，这些高度复杂的工业巨无霸们在研制过程中还需要众多零部件供应商的高度配合。
例如，芝加哥 L 线 (Chicago L) 新一代地铁列车 CTA7000 有 24 家供应商，中国首艘大型邮轮爱达·魔都号有 361 家供应商，民航史上最成功的机型之一波音 737 有 600 多家供应商。
无论是地铁公司、航空公司还是船东，运营商们都会要求制造商随产品一起交付内容完整、风格统一、正确无误的产品手册。
如果没有统一的规范，各个供应商在编写手册时自成一派，那制造商就必须按照自己的写作规范将所有的供应商手册重写一遍，才能将这些内容整合进自己的手册里。
工作量巨大不说，一些零部件（尤其是核心零部件）的技术含量特别高，制造商通常难以驾驭、甚至无法驾驭这些零部件手册的内容重写工作。
即使是技术文档写作规范相对成熟的航空航天业，制造商在整合纸质版和 PDF 版的供应商手册时也需要做大量的重复性编辑工作，比如文字录入、复制粘贴和手册排版等。
产品交付后，运营商需要根据产品手册制作作业指导书、维修卡片和培训材料等许多内部文件。在产品长长的寿命周期里，这些文件还需要根据手册的定期和不定期更新作出相应的修改。所以，大量枯燥的编辑工作也是运营商的恶梦。
为了解决运营商、制造商和供应商在手册内容协作共享上的面临的困境，S1000D 规范除了能像其他结构化标准一样进行同源发布以外，还支持各方以文件数据包的形式进行数据交换。
文件数据包里有数据模块（DM）、出版物模块 (PM)、数据模块里引用的所有插图和多媒体文件、以及记录文件数据包中所有文件信息的数据分发说明 (DDN) 等。
当然，S1000D 也为文件数据包制定了打包规则，比如文件命名规则、数据包内应该包含的文件种类和数量等。
定制方式
S1000D 规范最初是专为军用飞机制定的技术文档编制规范，后来逐渐将适用范围扩展到各类军用和民用的海陆空装备。
当一个企业或项目决定应用 S1000D 时，必须根据自身情况从 S1000D 规范中挑选出适合自己的部分。这个挑选过程，在 S1000D 中被称为裁剪 (tailoring)。
对于 S1000D 来说，裁剪有两层含义：
第一，去除不需要的部分。例如，S1000D 中定义了 20 多种数据模块类型，但如果船东要求制造商按照 Shipdex 2.3 交付产品手册，那么制造商就只能挑选出三种类型的数据模块来用 —— 描述类 (Descript)、维修程序类 (Procedure) 和图解零件数据类 (IPD)。
在上面的例子中，制造商在手册编制过程中也可以挑选更多的数据模块来用，比如适用性类数据模块和业务规则交换类数据模块。但是，制造商向船东交付的文件数据包里只能包含上述三种类型的数据模块。
也就是说，如果制造商在手册编制过程中使用了其他类型的数据模块，就必须在打包前完成对其他类型数据模块的解析。
第二，禁止创建新“枝叶”。例如，S1000D 中定义了三个等级的安全信息 —— 警告 (<warning>)、小心 (<caution>)和提示 (<note>)，如果船东要求制造商按照 ANSI Z535 的要求编写手册中的安全信息，那么制造商只能通过为 <warning> 设置属性的方式来标记“危险 (Danger) ”等级的安全信息，而不是自行创建一个新元素 <danger>。
ANSI Z535 定义了四个等级的安全信息：危险 (Danger)、警告 (Warning)、小心 (Caution) 和注意 (Notice)。
Shipdex 对于 ANSI Z535 型安全信息的元素和属性使用规定
| ANSI Z535 | 元素 | 属性 |
|---|---|---|
| Danger | <warning> |
vital = 1 |
| Warning | <warning> |
vital = 0 |
| Caution | <caution> |
type = 0 |
| Notice | <caution> |
type = 1 |
裁剪的两层含义，意味着 S1000D 不具备任何扩展性。正是这种无扩展性设计，为企业与企业之间进行数据交换提供了最大程度的便捷。
否则，如果制造商创建了新元素 <danger>，而船东的发布程序不认识 <danger>，还会将其标记为非法元素，这就尴尬了！
为了让用户快速上手，S1000D 规范提供了一个叫做业务规则决策点索引的裁剪工具。这份索引就像一份调查问卷一样，里面包含 500 多个问题，比如：
- 请问你需要使用哪个版本的 S1000D?
- 请问你需要用到 S1000D 中的哪些信息集?
- 请问你是否需要使用
@warningType属性? 如果使用，怎么用?
当然，不是每个问题都必须回答，根据自身情况挑选跟自己相关的问题就行了。如果需要，你还可以提出新问题。
问题回答完了，裁剪也就完成了。裁剪形成的答卷，叫做业务规则。裁剪中使用的问题，叫做业务规则决策点 (BRDP)。
实施成本
S1000D 是一种开放的标准，你可以通过 S1000D 官网免费下载或在线阅读。
但 S1000D 并没有开源，不仅相关的开源软件特别特别少，而且免费的学习资源也不多。
这种资源贫瘠的状况，自然与 S1000D 较高的入门门槛脱不了干系。
最新版 S1000D 规范（PDF版）有 3500 页左右，文档长度远远超过其他结构化标准。除了前文提到的诸多内容之外，S1000D 还可以提供源数据管理、公共信息库 (CIR)、技术插图的制作规范以及用于信息管理的各种编码规范等等等等~~
说它包罗万象、事无巨细一点也不为过，但学习难度也高啊！一般情况下，从传统的文档编制方法过渡到 S1000D 都需要专家指导。否则，过渡期会变得相当漫长，甚至会长到无法接受。
其实，大多数主流的结构化文档编辑器和内容管理系统都支持 S1000D。只是由于选择使用 S1000D 的都是结构复杂、专业性强、使用寿命长的产品，需要更多的开发工作，所以部署 S1000D 的价格会高一些。
按照 @技术传播百态说 的光荣传统，文末提供一点零星的资源：
参考资料
- 马小骏, 吉凤贤等. 基于S1000D规范的民用飞机维修类技术出版物开发技术[M]. 北京: 科学出版社, 2017.
- Blandineau D, Ferland M, etc. A Presentation on S1000D User Form 2013: RailDex [OL]. [2013-9-16][2024-1-7].
- Shipdex. The Shipdex Protocol, Issue 2.3 [M/OL]. [2015-6-20][2024-1-7].
- Fandom. Metro Wiki: 7000-series (CTA) [OL]. [2022-2-18][2024-1-7].
- 新华网. 国产首艘大型邮轮“爱达·魔都号”开启商业首航[OL]. [2024-1-2][2024-1-7].
- Elaine Schwartz. A Global Look at the 737 MAX [OL]. [2020-1-13][2024-1-7].
- 轩振原等. 基于S1000D的动产组IETM管理平台研究[J]. 计算机应用, 2022, 31(3): 42-47.
- 王辉等. 基于S1000D的动车组技术信息结构化方法[J]. 中国铁路,2016(2):5.
