ZStack Documentation DevOps Platform Construction And Practice

I. Introduction

Documentation is a critical component of software products. Product documents, such as release notes, user guides, API references, installation tutorials, and scenario-based tutorials, help users quickly understand and adopt products. The tight integration between software and documentation presents a challenge for companies: how to maintain agile and efficient documentation workflow amid rapid business changes and frequent software updates.

This article explores how ZStack successfully constructed its Documentation DevOps platform to optimize documentation workflow. It details ZStack’s structured writing methodology, version control strategy, DevOps platform architecture, and challenges and solutions during the platform construction.

II. Foundation of Documentation DevOps: Structured Writing

In software development, “Docs as Code” is a widely accepted methodology. Its core principle is to treat documentation as code and integrate it into the software development lifecycle. Traditional writing methods, lacking modularization and standardization, often fail to meet the efficiency requirements of “Docs as Code”. Structured writing has thus emerged as an effective solution for improving documentation development and release efficiency.

Structured writing emphasizes information architecture. DITA (Darwin Information Typing Architecture), originally developed by IBM and adopted as an open standard by OASIS in 2005, is a widely used international standard for structured writing. As an XML-based framework, DITA provides critical capabilities, including content-formatting decoupling, content reuse, and filtering and customization, significantly enhancing documentation development’s flexibility and standardization.      

Figure 1: Features of DITA

1. Content-Formatting Decoupling

In DITA-formatted documentation, information is organized into modular components. DITA defines multiple module types for structuring information hierarchically. The following are commonly used module types:

• DITAMAP: A DITAMAP, usually used at the top level, serves as the framework of a document. It defines which topics are included and how they are organized in the document.
• TOPIC: A TOPIC functions as a chapter in a document. To accommodate different writing scenarios, DITA employs the DTD mechanism to categorize topics into various types, such as Concept, Task, Troubleshooting, and Reference, and define the basic structure of each topic type (specifically, the labels that must or cannot be contained in a topic type). This ensures the standardization and consistency across topics serving similar scenarios.
• LABEL: A LABEL represents any content element within a TOPIC – including paragraphs, sentences, phrases, lists, tables, and images. Multiple LABELs combine to form a complete TOPIC.

During the document development, technical writers establish the document architecture at DITAMAP and TOPIC levels and write content at the LABEL level. This ensures they work in a standardized framework and produce well-organized documents with clear hierarchies.

Figure 2: TOPIC DTD

2. Content Reuse

DITA supports content reuse at different modular levels, including DITAMAP, TOPIC, and LABEL.

• DITAMAPReuse: A DITAMAP (e.g., DITAMAP A) can be nested into another  (e.g., DITAMAP B). Therefore, DITAMAP B reuses all content from DITAMAP A and preserves the structure defined in DITAMAP A.
• TOPICReuse: A TOPIC can be included in multiple DITAMAPs. Therefore, all these DITAMAPs share the same TOPIC.
• LABEL: A LABEL can be referenced across multiple TOPICs. Therefore, all these topics share the same sentence, table, image, or other elements.

During documentation updates, the reuse mechanism reduces redundant effort and ensures information consistency. Once the source content is modified, all references are automatically synchronized.

In ZStack’s documentation, key elements like product names, versions, and terminologies are centrally managed in a reuse source file. When updates are required, technical writers only need to modify the reuse source.

Figure 3: TOPIC Reuse

3. Filtering and Customization

During the documentation release, configuration files (DITAVAL and DITA-OT) control the content and presentation of deliverables. By editing these files,  technical writers can generate documents with varying formats, editions, styles, and content from the same DITAMAP, enabling flexible customization for various publishing channels and business requirements.

• DITAVAL：Enables content customization through conditional filtering. Technical writers can tag TOPICs or LABELs and define inclusion/exclusion rules in DITAVAL to define which tagged content appears in final deliverables.
• DITA-OT: Defines the visual presentation of deliverables, including the document format, cover, font type, font size, color, header, and footer.

Following the DITA standard, ZStack has developed a large-scale structured documentation system containing tens of millions of characters. The system’s modularization and standardization lay a solid foundation for DevOps platform construction.

Figure 4: Structured Documentation System

III. Documentation Version Control Strategy

ZStack leverages a Git repository for documentation version control.

As a distributed version control system widely used in the software industry, Git enables collaboration by allowing developers to commit and push local work to the remote repository and fetch the latest updates. Git’s robust branching capability allows multiple branches within a single repository, each branch dedicated to a specific task. This enables developers to work on multiple tasks in parallel without interference. When necessary, these branches can be merged for code consolidation.

Let’s take ZStack Cloud documentation as an example to demonstrate how this branching mechanism works in documentation development. At the start of a version cycle, technical writers create feature branches based on the stable master branch. Each feature branch documents a specific feature. When a feature branch stabilizes, it is merged back into master. After all feature branches are merged and the master branch content is verified as release-ready, a release branch is created from master for the final release.

During this process, technical writers can also handle urgent needs flexibly by creating bugfix branches to fix bugs, or custom release branches to deliver tailored documents for critical projects.

Figure 5: ZStack Cloud Documentation Branch

By implementing Git-based version control, ZStack’s documentation workflow is comparable to software code development in terms of standardization and manageability, further strengthening the foundation for the DevOps platform.

IV. Design Approach of ZStack Documentation DevOps Platform

With structured content and version control in place, ZStack’s documentation system is ready for CI/CD implementation and forms the foundation for the Documentation DevOps platform.

In software development, CI/CD is an automated solution for continuous code integration, testing, and deployment, enabling rapid and reliable software delivery. Extending this concept to documentation, documentation CI/CD automates batch document building, storing, and returning, providing a one-stop solution for rapid, reliable, and high-quality document delivery.

ZStack Documentation DevOps Platform is built on a microservice architecture. It leverages ZStack Cloud and Kubernetes（K8s）for service containerization and dynamic orchestration, automating the entire documentation delivery process through coordinated scheduling among microservices.

Figure 6: ZStack Documentation DevOps Platform Architecture

1. Security Mechanism

• Internal/External Network Reverse Proxy

Maps internal network Flask proxy server ports to external ports to enable secure external access (in some scenarios, applicants need to apply for and receive documents through an external platform) while maintaining strict internal/external network isolation. This solution ensures the internal service security by exposing only the service APIs and verifying all external requests via the reverse proxy.

2. APILayer

• FlaskProxy Server

Initially processes requests, parses request parameters, triggers document builds, and retrieves document build records.

• Build Task Management UI

Provides a visual interface for technical writers to manage document mapping configurations (the mapping relationships between essential files required for the document build, including DITAMAP, DITA-OT, and DITAVAL) and to manually trigger document build tasks.

3. Infrastructure Layer

• DevOpsCluster

A platform for managing the company’s internal production environments, integrating CI/CD pipelines.

• Jenkins K8s Cluster

Executes document builds in unit of task.

• Database

Stores task parameters, execution records, and Metadata.

4. Task Execution Layer

• Request Parameter Processing
• Parameter Standardization

Validates request parameters, modifying/filtering non-compliant parameters and preprocesses compliant parameters for use in subsequent flows.

• Workspace Allocation
• Document Code Isolation

Uses multiple workspaces to achieve code isolation, each workspace managing codes fetches from a specific document branch.

• Document Configuration File Modification
• DITA-OT/DITAVAL Parameter Modification

Dynamically adjusts parameters in DITAVAL and DITA-OT files to meet various business requirements.

• Document Build
• Log Generation

Generates standardized and visualized logs that include DITAVAL/DITA-OT parameters and DITA-OT output. These logs are used to verify whether the build is successful.

• Document Generation

Generates documents as required and uploads them to MINIO object storage.

V. Challenges and Solutions During DevOps Platform Construction

1. Configuration Conflicts in Batch Builds

To ensure document build efficiency and standardization, the DevOps platform builds documents in unit of task. Each task involves parallel build of multiple documents that may share the same DITAVAL/DITA-OT files but require different DITAVAL/DITA-OT parameters.

To resolve this conflict, the DevOps platform introduces the workspace mechanism, grouping documents requiring the same DITAVAL/DITA-OT parameters into the same workspace and configure DITAVAL/DITA-OT respectively for each workspace.、

2. Dynamic Maintenance of Configuration Files

The parameters in configuration files (DITAVAL and DITA-OT) vary based on business requirements – such as those used to define product names and brands in deliverables. To accommodate diverse business needs, these parameters must be dynamic and easy to maintain. The DevOps platform uses a dedicated configuration file set to centrally manage these parameters. Therefore, parameter adjustment can be made within this file set, eliminating the need for frequent modifications to the CI/CD code.

In addition, the DevOps platform maintains DITA-OT files centrally on a dedicated branch of the document repository. During document builds, the platform replaces the DITA-OT files in each workspace with those from the dedicated branch, minimizing changes to the content on the main document branches.

3. Log Optimization

A document build task may involve build of multiple documents. When a task fails or certain documents encounter errors, it becomes difficult for technical writers to locate and analyze the root causes within the extensive logs.

To address this challenge, the DevOps platform improves logs’ readability. Once a build task completes, the platform automatically generates a comprehensive and visualized log file that summarizes the DITA-OT output and DITAVAL configurations for all documents in the task, enabling technical writers to quickly identify and analyze any issues.

VI. Values of ZStack Documentation DevOps Platform

1. Enables Visualized and Convenient Management of Document Release Process

The DevOps platform provides a one-stop solution for document release – from managing document mapping configurations, triggering document builds, tracking build progress, to diagnosing issues. The platform uses a unified UI to visualize and streamline document release workflows, enabling complex processes to be managed with ease.

Figure 7: Document Mapping Configuration Management

Figure 8: Document Build Task Management

Figure 9: Visualized Log

2. Enhances Document Release Performance and Efficiency

Leveraging the power of the DevOps cluster, the DevOps platform provides robust computing and flexible resource scheduling for document builds, significantly reducing build time. This improvement is especially noticeable in large-scale document builds. For example, when releasing the full ZStack Cloud document system, the DevOps platform reduces build time by 50% compared to traditional release methods.

In addition, the DevOps Platform integrates with an external applicant platform. Business personnel can submit applications from this platform and automatically trigger document customization, builds, and deliveries. During this process, technical writers only need to review build results and address failed tasks.

VII.  Conclusion

Workflow optimization is a critical driver for enterprise efficiency. The ZStack Documentation Team continues to explore and implement agile documentation development and management methodologies.

In an era of rapid technological advancement, leveraging new technologies to drive tool innovation based on business requirements and strategically integrating these tools into daily workflow is essential for boosting productivity and efficiency. This is a crucial challenge that every modern professional must address. Let’s move forward together.