ZStack文档DevOps平台建设实践

（一）前言

对于软件产品而言，文档是不可或缺的一环。文档能帮助用户快速了解并使用软件，包括不限于特性概览、用户手册、API手册、安装部署以及场景实践教程等。由于软件与文档紧密耦合，面对业务的瞬息万变以及软件的飞速迭代，如何敏捷高效开发文档，是摆在每个软件公司面前必须攻克的难题。

本文从ZStack文档实践出发，围绕结构化文档开发、结合实际业务的文档版本管理策略、文档DevOps平台设计思路、实际建设难题与攻克等要点，向大家全面深入介绍ZStack文档DevOps平台建设的成功实践。

（二）结构化文档开发是前提

在软件开发领域，“Docs as Code”的文档开发理念已深入人心。该理念的核心思想是将文档作为代码的一种形式，将其纳入到软件开发生命周期中。传统的非结构化写作缺乏模块化和标准化机制，很难满足“Docs as Code”高效编写发布文档的要求。在此背景下，结构化写作应运而生，成为解决以上问题的有效方案。

结构化写作十分重视信息架构设计。DITA作为结构化写作的国际标准之一，已在业内广泛使用。DITA（Darwin Information Typing Architecture）最初由IBM公司开发，并在2005年被开放标准组织OASIS收录为开放标准。作为基于XML的体系结构，DITA通过内容与形式分离、内容重用、过滤与定制等机制，充分实现文档开发的灵活性和标准性。

图1. DITA的特点

1.内容与形式分离

DITA按模块组织文本内容，支持DITAMAP、TOPIC、LABEL等不同层级的模块化。

DITAMAP：DITAMAP是一本文档的框架，定义文档中包含哪些TOPIC以及TOPIC的组织形式。
TOPIC：TOPIC是一个完整的主题或章节。DITA提供了适用于不同场景的多种TOPIC类型，例如：Concept、Task、Troubleshooting、Reference，并通过DTD规定这些TOPIC的基本架构（即规定TOPIC必须或只能包含哪些LABEL），从而保证同类型主题/章节的规范性和风格一致性。
LABEL：LABEL是TOPIC中的标记对，通常是组成一个TOPIC的各种元素，包括段落、句子、短语、表格、列表、图片等。

在文档开发阶段，开发者按照规范，逐级组织DITAMAP和TOPIC架构，并在LABEL层级进行内容编写。这样，既保证了开发者始终在框架规范内进行创作，也使得最终输出的文档层次分明。

图2. TOPIC DTD

2.内容重用

DITA支持以模块为单位进行不同粒度的内容重用。DITAMAP、TOPIC、LABEL均适用重用机制。

DITAMAP重用：将一个DITAMAP A嵌套到另一个DITAMAP B。这样，DITAMAP B可以重用DITAMAP A的全部内容。
TOPIC重用：一个TOPIC可以拖动到多个DITAMAP中。这样，多本文档可以重用相同的章节内容。
LABEL：一个LABLE可以引用到多个TOPIC中。这样，多个章节可以重用相同的句子、表格或图片。

在文档迭代过程中，重用机制既减少了重复劳动也保证了文档内容一致性。一旦重用来源被修改，所有引用均会被更新。在ZStack技术文档中，产品名称、产品版本、术语等均以重用的形式出现在各个文档、各个章节。一旦发生变动，这些被广泛使用的内容可“牵一发而动全身”。

图3. TOPIC重用

3.过滤与定制

在文档发布阶段，配置文件DITAVAL和DITA-OT决定了输出文档的内容和样式。通过调整DITAVAL和DITA-OT，基于同一本DITAMAP可以发布不同内容、不同格式、不同风格的文档，面对多样化的业务需求和发布渠道可实现灵活定制。

DITAVAL：DITAVAL用于对文档内容进行条件过滤。开发者可以在DITAVAL中定义某个标签在输出文档中被剔除/包含，并给需要过滤的TOPIC、LABEL标记对应的标签。在文档输出过程中，DITAVAL自动识别标签，使对应的内容最终被呈现/隐藏，实现不同业务场景下的文档内容定制。
DITA-OT：DITA-OT用于定义文档发布样式，包括文档格式、封面、字体、字号、颜色、页眉、页脚等。灵活配置DITA-OT，可使文档输出为多种格式（PDF、HTML等）以配合不同的发布渠道，或改变文档样式风格，实现多样化定制需求。

ZStack基于DITA构建了庞大的结构化文档库，总文字规模超过千万级。由于高度模块化和标准化，为实现文档DevOps奠定了坚实基础。

图4. 结构化文档库

（三）结合实际业务的文档版本管理策略

ZStack文档库采用GIT仓库托管，通过GIT机制实现文档版本控制。

在软件开发领域，GIT是一种被广泛使用的分布式版本控制系统。开发者在本地完成工作，通过Commit、Push操作提交至远端，并通过Pull操作获取远端更新。GIT提供强大的分支管理功能，开发者可依据业务需要，灵活创建独立分支，每个分支专注于特定任务，互不冲突。必要时，可通过分支合并实现内容汇总。

以ZStack Cloud技术文档开发为例，在新版本开发之初，开发者基于稳定的主分支（Master Branch）开出多个特性分支（Feature Branch），并在特性分支进行独立开发，各特性分支稳定后全部并入主分支。期间，可按需开出Bugfix分支修复问题，还可灵活响应定制项目插队，随时开出定制分支（Customized Branch）进行定制开发。最终，基于主分支评估开出合适的发布分支（Release Branch），用于最终发布。