Using GitHub and ReadTheDocs for Collaborative Documentation: A Hands‑On Training Overview

During a training session at Microsoft Shanghai R&D Center, the author shares a new approach to writing technical documentation by leveraging open‑source tools.

Instead of traditional static documents, the author uses reStructuredText (a lightweight markup similar to Markdown) as the source format, which keeps the content independent of its presentation.

The documentation source is stored in a GitHub repository, allowing version control, easy collaboration, and the ability to edit directly via the "Edit on GitHub" link.

ReadTheDocs.org is used to automatically build the documentation into HTML, PDF, ePub and other formats, providing a responsive layout that works on both desktop and mobile browsers.

Key advantages highlighted include:

The content is format‑agnostic and remains readable as plain text.

Source files are easy to compare and merge using standard diff tools.

Multiple output formats are generated automatically.

Version control and pull‑request workflows enable distributed teamwork.

The training demonstrates the full workflow: creating a main repository on GitHub, forking it for collaborators, editing files, submitting pull requests, and configuring a webhook so that each push triggers an automatic build on ReadTheDocs.

Participants can view the generated documentation on PCs and smartphones, and provide feedback or report issues via GitHub issues.

All related resources are shared, including the documentation site (https://vsalm-hols.readthedocs.org) and the GitHub repository (https://github.com/ups216/vsalm-hols), inviting readers to explore, fork, and contribute.