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），用于最終發布。