Evolution of the DevOps Documentation Center from v0.5 to v2.0

The post introduces the background of a Git‑based developer tutorial and explains why traditional document folders become chaotic, motivating a more systematic approach to technical documentation.

It recounts the first version (v0.5) of a DevOps documentation center built in 2016 using Python reStructuredText and ReadTheDocs, hosted on GitHub and readthedocs.org.

Subsequent efforts produced over 20 training document sets across more than 40 Git repositories, covering topics such as Microsoft Cloud Development Bootcamp, Docker‑based DevOps training, Apache Mesos, and Jenkins.

Version 1.0 consolidated these resources into a single indexed portal, providing a unified entry point for all documentation.

Version 2.0 addressed three main pain points: the unfamiliar reStructuredText syntax, the growing scale of the repository (over 2,000 pages and 200,000 lines of source), and the difficulty of customizing the Sphinx‑based build pipeline.

To solve these issues, the team switched to MDWIKI, converting Markdown to HTML directly in the browser, and adopted Git submodules to aggregate multiple documentation repos while keeping the main repository lightweight.

The new workflow uses two core Git repositories (home and mdwiki). Documentation lives in independent repos linked via submodules, allowing developers to see the structure through submodule references and keeping the main repo small. Azure App Service hosts the front‑end, while TFS pipelines publish the content, and a bidirectional sync with GitHub enables community pull‑requests and future comment features.

Links to the live documentation site, the specific GitHub repository, and the publishing page are provided, illustrating the current state of the DevOps documentation hub.

The article concludes by noting remaining challenges, such as maintaining navigation, and mentions plans to automate title scanning for navigation generation, while reaffirming the team’s expertise in DevOps implementation.