结构化文档和通用的文档方法(比如:MS Word、Markdown)的一个重要区别是结构化方法可以出版个性化文档。
这里所说的个性化文档指的是文档中只包含与某种产品、或者某个用户角色相关的内容,和它不相关的内容在发布过程中被过滤掉。
比如,我们写Windows操作系统的用户手册。我们知道Win 11和Win 7操作大部分是一样的,但是控制面板的操作不一样。所以,我们决定在一个用户手册中包含Win 11和Win 7的内容。对于控制面板的操作,结果如下:
如果当前使用的是Win 11,请这样操作:
1. xxxxx
2. xxxxx
3. xxxxx
如果当前使用的是Win 7, 请这样操作:
1. yyyyy
2. yyyyy
3. yyyyy
写一个用户手册比为两个操作系统分别写用户手册的好处是减少了很多重复的内容。但是,用户在使用的时候需要做判断,要根据当前自己使用的操作系统,选择相关的内容。这会增加用户的使用难度,降低工作效率。
使用结构化文档的个性化发布,则在出版Win 11用户手册时把Win 7相关的内容过滤掉或者用赋予灰色背景表示无效。 这样可减少用户做判断,提高使用效率,这在用户处于紧急情况尤其重要。
实现个性化出版包括2步:
-
在编辑内容时标识内容的有效性
-
发布文档的时候过滤内容
不同的结构化文档标准使用的不同的有效性模型。这篇文章来聊聊这些不同的有效性模型。
- 1 -
DITA的有效性模型
DITA是使用得很广泛的一种结构化文档标准。它是基于XML的体系结构,用于编写、制作、交付面向主题的信息类型的内容。DITA可用于技术手册、交互培训,教材、标准、报告、商业文档、贸易书籍、旅游和自然指南等书籍的编写。
在DITA中,预先定义了这5个属性用于内容过滤:
-
platform - 操作系统,如:windows, mac, linux
-
product - 产品,如:win11, win10
-
audience - 读者类型,有:novice - 新手,expert - 专家
-
props - 属性
-
otherpros - 其他属性
其中,platform、product、audience有一定意义,而props和otherpros则预先无意义。文档组可以决定怎样来使用这几个属性,即:根据自己的需要决定让它们代表什么意义。
DITA的有效性模型通过使用属性来标识内容的有效性,属性的值可以是一个或者多个,使用逗号分割。
模型定义如下:
<!ENTITY % filter-atts
"props CDATA #IMPLIED
platform CDATA #IMPLIED
product CDATA #IMPLIED
audience CDATA #IMPLIED
otherprops CDATA #IMPLIED
%props-attribute-extensions;"
>
样例数据1:
<section id="id-0012" audience="expert">
<title>高级功能</title>
<ul>
<li>
<p>智能分析:支持提取照片拍摄的时间、地点信息,支持对照片进行分类打标,目前支持多达 5000 类的事物识别能力。</p>
</li>
<li>
<p>人脸识别:支持识别用户照片中面孔,智能云相册将自动把属于同一面孔的照片归类在一起,这样就能快速找到同一面孔的所有照片。</p>
</li>
</ul>
</section>
代表这个section的内容针对expert(专家)有效。
样例数据2:
<p product="win11">智能云相册服务基于飞腾云云计算服务构建,它解决了以往搭建云相册后端服务过程中,需要购买、搭建和运维 ECS
集群,集成其他云计算服务(对象存储、媒体转码等),处理海量用户的高并发请求等一系列繁琐的问题。更重要的是,它提供了对影像内容的智能分析,智能生成相簿和智能搜索等服务,让人工智能技术变得触手可及,极大提高企业和个人用户构建云相册应用程序的效率。</p>
代表这个段落的内容针对win11这个产品有效。
在发布时,通过提供一个DITAVAL文件来描述过滤条件。 比如:以下DITAVAL文件标识发布的内容不包含audience=expert的内容。
<?xml version="1.0" encoding="UTF-8"?>
<val>
<prop action="exclude" att="audience" val="expert"/>
</val>
发布的结果就是针对初学者的内容。
- 2 -
ATA 2200的有效性模型
ATA iSpec 2200是一个全球航空业标准,用于飞机工程和维护信息的内容、结构和电子交换。它包括一套与维护要求和程序以及飞机配置控制有关的数据规范。
ATA iSpec 2200提供以下文档类型定义:
-
飞机维修手册 (AMM)
-
飞机图示零件目录(AIPC)
-
部件维护手册(CMM)
-
发动机图示零件目录(EIPC)
-
故障报告手册(FRM)
-
飞行机组操作手册(FCOM)
-
主最低设备清单(MMEL)
-
等
在ATA 2200中,有效性模型定义如下:
<!ELEMENT effect - - ((sbeff | coceff)*) >
<!ATTLIST effect
effrg CDATA #IMPLIED
efftext CDATA #IMPLIED
efftype CDATA #IMPLIED
efflen NUMBER #IMPLIED >
文档类型中定义了有效性标签effect,它有4个属性,其中含义:
-
effrg - 有效性的飞机编号的范围
-
efftext - 有效性的说明文字
-
efftype - 有效性类型
-
efflen - 飞机编号长度
注:飞机制造商为其出厂的每一架飞机进行了编号,叫做MSN (Manufacturer Serial Number),比如001,002等。effrg中的范围指的是从第几架飞机到第几架飞机。
样例数据:
<PRCITEM2>
<EFFECT EFFRG="003006 024025" EFFTEXT="Batch 1">
<SBEFF EFFRG="003006 024025" SBCOND="POST" SBNBR="32-1392">
</EFFECT>
<PRCITEM>
<TITLE>Trouble Shooting Manual (TSM) Objective </TITLE>
<PARA>The TSM is provided by ABC to enable the systematic identification,
isolation and correction of aircraft warnings and malfunctions reported in flight and on the ground. </PARA>
<PARA>NOTE TO USERS : </PARA>
<PARA>If you cannot find a fault symptom and/or a fault isolation procedure
necessary to ensure the continued airworthiness of the aircraft, or if you think that the information given
is not complete, contact ABC. </PARA>
</PRCITEM>
</PRCITEM2>
表示PRCITEM2的有效性是:编号为003到006的飞机和024到025的飞机且已经执行了编号为32-1392的服务通告。(即:003,004,005,006,024和025这5架飞机)。
发布手册时,如果发布的是针对第006架次的手册,则这个PRCITEM2会包含在发布结果中。
如果发布的是针对007架次的手册,则这个PRCITEM2会被过滤掉。
- 3 -
S1000D的有效性模型
S1000D最初是由欧洲航空工业联盟开发的技术出版物规范,它主要为具有较长生命的复杂产品运行和维修而设计。这些年不断发展,已经扩展到这些行业的产品:国防系统 - 包括海、陆、空的产品,民用航空产品,基建行业产品和船舶工业产品。
S1000D中适用性机制由数据模块、发布模块、数据管理列表、数据更新文件中的适用性注释以及三种特定的数据模块类型支持:
-
适用性对照表(ACT)数据模块
-
条件对照表(CCT)数据模块
-
产品对照表(PCT)数据模块
ACT、CCT和PCT数据模块分别在ApplicCrossRefTable.xsd, CondCrossRefTable.xsd以及ProductCrossRefTable.xsd 中定义。
适用性对照表(ACT)数据模块用于声明产品属性。产品属性是指对技术数据的适用性有影响的产品属性。产品属性是产品的属性,通常在产品实例制造时设置,并且在产品实例的整个使用寿命内通常不会更改。产品属性的示例包括型号、系列和序列号。
条件对照表(CCT)数据模块用于声明任何可能影响数据适用性的条件。条件可以是技术性的、操作性的、环境性的,也可以是任何其他可能影响技术数据的类型。
产品对照表(PCT)数据模块是一个存储库,用于定义产品实例并将值与每个产品实例的产品属性和条件相关联。产品实例是实际的实物产品,例如序列号为1B070643的Brook trekker Mk9自行车。
样例数据:
<applic>
<displayText>
<simplePara>SN: 1-2, 5-10 or (SN: 3-4 Post SB SB-0001)</simplePara>
</displayText>
<evaluate andOr="or">
<assert applicPropertyIdent="serialno" applicPropertyType="prodattr" applicPropertyValues="1~2|5~10" />
<evaluate andOr="and">
<assert applicPropertyIdent="serialno" applicPropertyType="prodattr" applicPropertyValues="3~4" />
<assert applicPropertyIdent="SB-0001" applicPropertyType="condition" applicPropertyValues="Post" />
</evaluate>
</evaluate>
</applic>
有效性的为:
(飞机编号:1-2, 5-10) 或者 (飞机编号: 3-4 并且执行了 SB-0001)
注:SB是Service Bulletin的缩写,代表服务通告,是飞机制造商与飞机运营商(航空公司)沟通的一种文件。 航空公司根据SB的内容会对飞机做某种工作。因为做了这项工作可能会引起飞机的变化,所以执行工作后可能引起操作程序的变化 。
- 4 -
分析总结
DITA中的有效性模型定义比较宽泛,默认有5个属性可用,相对ATA2200和S1000D更简洁。文档组可以定义内容的有效性。从管理粒度来讲,它定义内容对某一类产品、某一类用户有效,但不具体到每一个具体的产品。可以出版针对某一类产品、某一类用户的文档,但不能出版针对某一个产品的文档(也许是没有这个需要)。
ATA2200和S1000D的有效性模型定义更具体,默认提供了产品属性和条件,其中并没有定义针对某类用户的属性。从管理粒度来讲,它定义了内容对一个具体的设备的有效性。这样可以出版针对某一个设备的的手册。
问:
-
你的行业需要出版针对某一个具体的产品的文档吗?
比如:出版针对A品牌的、编号为1234这个产品的文档。
-
你认为为什么DITA、ATA、S1000D的有效性模型是这样定义的?
公众号:大龙谈智能内容
访问摩拿官网联系我们