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