ServiceNow公司的DITA内容质量管控实践

在DITA文档管理领域，如何通过有效的质量管控机制保障内容质量，是许多技术文档团队面临的核心问题。

近日，Dometic公司技术文档负责人Stefan Jung在DITA用户组发起提问，聚焦GitHub环境下DITA仓库的质量管控建设，引发了行业内的关注与探讨。ServiceNow的高级内容工程师Eliot Kimber结合自身实践，分享了一套全面的文档质量管控方案，为行业提供了宝贵参考。

提问：想了解使用Oxygen + Git方案的同仁怎样进行内容质量管控

我很想了解，其他团队是如何在 GitHub 环境中落地质量管控机制的。若你能分享相关实践思路 ------ 尤其是如何基于以下技术手段，为 DITA Map文件与 DITA 主题文件搭建质量管控机制，我将不胜感激：

• XML 语法校验（采用 Relax NG 语法规则）

• Schematron 规则校验

• Vale 语法检查器规则校验

• 人工智能技术校验

• 代码格式规范化校验

理想情况下，这些质量检测数据还能同步至 PowerBI 报表中。或许我们可以互通思路，就此主题联合撰写一篇技术文章。

感谢你的分享。

回答：ServiceNow的质量管控实践

在 ServiceNow，我们已部署以下验证与准入流程：

1. 基于 Schematron 的规则校验 用于检查两类规则：1) 导致构建失败的硬性规则； 2）编辑规范类软性规则。这些 Schematron 规则在两个场景生效：

   • 编辑阶段：直接集成在 Oxygen 编辑器中，支持对 DITA Map文件的实时验证；

   • 批量验证阶段：通过 Oxygen 命令行验证工具执行，验证报告统一归集到 Mirabel 信息系统。该系统提供验证仪表盘和验证结果的历史记录，便于我们追踪规则合规性的长期趋势（理想状态下是持续向好）。多年来，我们投入大量精力构建自定义 Schematron 规则，同时也直接沿用了 Oxygen 内置的 DITA 标准 Schematron 规则集。

2. Git 提交钩子校验在代码提交阶段强制触发以下检查：

   • 文件命名规范

     确保文件名不含空格；

   • XML 格式合法性

     校验所有 XML 文件（包括 DITA 主题、Map文件及 SVG 文件）是否格式完好；

   • DTD 有效性

     验证 DITA Map与主题文件是否符合对应的 DTD 规范；

   • 引用文件路径正确性

     由于内容管理机制的特殊性，极易出现跨层级的 "越界引用"，这类问题会直接导致构建失败，钩子会对此进行拦截；

   • 文件修改权限管控

     弥补 Git 本身不支持文件级权限管理的缺陷，防止作者修改无权操作的文件。例如，共享的核心定义文件仅允许内容架构团队编辑。

3. 基于 Acrolinx 的文本质量检查通过 Oxygen 插件集成 Acrolinx 工具，开展文本可读性、术语一致性等维度的校验。我们未采用严格的受控词汇表，因此 Acrolinx 主要作为内容团队专职编辑的辅助工具（注：我们的产品内容组配备了专门的编辑人员）。

4. 构建流程的自动校验构建过程会主动检测可能导致输出无法发布的内容与标记问题（例如，在 Fluid Topics 流程中，若 HTML Map文件引用了缺失的 HTML 文件），一旦发现问题立即终止构建。

5. 人工编辑审核将人工审核纳入标准创作流程，作为质量把控的核心环节之一。

6. 基于 Content Fusion 的在线协同评审 该工具同时服务于主题专家（SME）技术评审 和编辑团队规范评审两个环节。

在未来一年，我们计划引入 AI 工具，一方面辅助内容创作，另一方面承担部分质量校验工作，不过目前尚未明确具体的落地形态。目前，ServiceNow 内部的 AI 基础设施才刚刚达到支撑创作与发布流程的水平 ------ 我的同事阿卜杜勒・乔杜里将在匹兹堡举行的 ConVEx 大会上，分享他在构建流程中集成DITA 主题 AI 摘要生成功能的实践经验。这一领域仍有大量探索空间，要打造出实用的工具还有很多工作要推进。

当前，我们尚未建立完善的发布前预览评审机制，作者无法直观查看内容发布后的最终呈现效果。不过明年这一情况将得到改善：随着文档网站从 Zoomin 迁移至 Fluid Topics 平台，作者将能在内容发布前几天，预览其最终展示形态。目前的发布工作流规定：内容在正式发布前两天进入冻结状态（我们的文档每月更新一次，历史上产品新版本的发布周期为半年一次）。未来，我们可能会调整这一时长，为发布前的评审与修正预留更充裕的时间。

我们面临的最大挑战，其实是培育全员重视验证与纠错的文化氛围。由于内容体量庞大，且作者始终承受着高强度的创作压力，如何引导他们主动投入时间解决验证问题，一直是我们需要攻克的难题。因此，我们并未将 Schematron 验证通过设为发布的强制准入条件。

得益于所有链接与图片均采用键控引用（key-based reference） 机制，我们可以通过标准的 DITA 验证流程确保内容中不存在失效链接。但需要持续投入精力维护键值的变更 ------ 尤其是跨文档的键值关联，某个文档中的键值修改，都可能导致其他文档的引用失效。

值得一提的是，过去一年左右落地的 Git 提交钩子，已经帮助我们基本杜绝了作者向代码库提交会导致构建失败的内容的情况。

Git 钩子的核心难点在于校验耗时的平衡：既要保证校验的全面性，又要兼顾提交的时效性。例如，如果在提交时运行全部 Schematron 规则校验，作者每次提交主题更新可能都要等待 5 分钟，这显然不现实。即便是仅执行 DTD 验证，其耗时成本也不低，但考虑到这项校验的必要性，我们认为这部分时间投入是值得的。

由于我们的团队统一使用 Mac 设备，因此 Git 提交钩子基于 Bash 脚本开发，并借助 xmllint 命令行工具完成 XML 相关的校验工作。

注：本文使用AI进行协助翻译，但未进行润色，以尽量保持原意。