博客

I. 引言
文档是软件产品的重要组成部分。产品文档，如发布说明、用户指南、API参考、安装教程和基于场景的教程，帮助用户快速理解和采用产品。软件与文档之间的紧密集成给公司带来了挑战：如何在快速的业务变化和频繁的软件更新中保持敏捷高效的文档工作流程。
本文探讨了ZStack如何成功构建其文档DevOps平台以优化文档工作流程。详细介绍了ZStack的结构化写作方法、版本控制策略、DevOps平台架构以及在平台构建过程中遇到的挑战和解决方案。
II. 文档DevOps的基础：结构化写作
在软件开发中，“文档即代码”是一种被广泛接受的方法论。其核心原则是将文档视为代码，并将其集成到软件开发生命周期中。传统的写作方法缺乏模块化和标准化，通常无法满足“文档即代码”的效率要求。结构化写作因此成为提高文档开发和发布效率的有效解决方案。
结构化写作强调信息架构。DITA（Darwin Information Typing Architecture），最初由IBM开发，并在2005年被OASIS采纳为开放标准，是结构化写作的广泛使用的国际标准。作为一个基于XML的框架，DITA提供了关键能力，包括内容格式化解耦、内容重用以及过滤和定制，显著增强了文档开发的灵活性和标准化。
图1：DITA的特点
内容格式化解耦
在DITA格式的文档中，信息被组织成模块化组件。DITA定义了多种模块类型，用于层次化地结构化信息。以下是常用的模块类型：
DITAMAP：DITAMAP通常用于顶层，作为文档的框架。它定义了哪些主题被包含以及它们在文档中的组织方式。
TOPIC：TOPIC作为文档中的一个章节。为了适应不同的写作场景，DITA采用DTD机制将主题分类为各种类型，如概念、任务、故障排除和参考，并定义每种主题类型的基本结构（具体来说，必须或不能包含在主题类型中的标签）。这确保了为类似场景服务的主题之间的标准化和一致性。
LABEL：LABEL代表TOPIC中的任何内容元素——包括段落、句子、短语、列表、表格和图像。多个LABEL组合形成一个完整的TOPIC。
在文档开发过程中，技术作者在DITAMAP和TOPIC级别建立文档架构，并在LABEL级别编写内容。这确保他们在标准化框架中工作，并产生组织良好、层次清晰的文档。
图2：TOPIC DTD
内容重用
DITA支持在不同模块级别上的内容重用，包括DITAMAP、TOPIC和LABEL。
DITAMAP重用：一个DITAMAP（例如，DITAMAP A）可以嵌套到另一个中（例如，DITAMAP B）。因此，DITAMAP B重用了DITAMAP A的所有内容，并保留了在DITAMAP A中定义的结构。
TOPIC重用：一个TOPIC可以包含在多个DITAMAP中。因此，所有这些DITAMAP共享相同的TOPIC。
LABEL：LABEL可以在多个TOPIC之间引用。因此，所有这些主题共享相同的句子、表格、图像或其他元素。
在文档更新过程中，重用机制减少了冗余工作，并确保了信息的一致性。一旦源内容被修改，所有引用都会自动同步。
在ZStack的文档中，产品名称、版本和术语等关键元素在重用源文件中集中管理。当需要更新时，技术作者只需要修改重用源。
图3：TOPIC重用
过滤和定制
在文档发布过程中，配置文件（DITAVAL和DITA-OT）控制交付物的内容和呈现。通过编辑这些文件，技术作者可以从同一个DITAMAP生成具有不同格式、版本、风格和内容的文档，实现对各种发布渠道和业务需求的灵活定制。
DITAVAL：通过条件过滤实现内容定制。技术作者可以标记TOPIC或LABEL，并在DITAVAL中定义包含/排除规则，以确定哪些标记的内容出现在最终交付物中。
DITA-OT：定义交付物的视觉呈现，包括文档格式、封面、字体类型、字体大小、颜色、页眉和页脚。
遵循DITA标准，ZStack开发了一个包含数千万字符的大规模结构化文档系统。系统的模块化和标准化为DevOps平台建设奠定了坚实的基础。
图4：结构化文档系统
III. 文档版本控制策略
ZStack利用Git仓库进行文档版本控制。
作为一个在软件行业广泛使用的分布式版本控制系统，Git通过允许开发人员将本地工作提交和推送到远程仓库并获取最新更新来实现协作。Git的强大分支能力允许单个仓库中有多个分支，每个分支专注于特定任务。这使得开发人员可以并行处理多个任务而不受干扰。必要时，这些分支可以合并以进行代码整合。
让我们以ZStack Cloud文档为例，展示这种分支机制在文档开发中的工作原理。在一个版本周期开始时，