Skip to content
Olivier CarrèreTechnical writing practice

Version management systems - rustic but reliable

Use Git or Subversion to manage technical documentation like source code: track changes, collaborate with your team, and roll back safely at any time.

, 2 min read

View as Markdown

Definition

Section titled “Definition”

Working with source files in text format, rather than binary, allows a technical writer to manage content similar to how developers manage code: using a Version controlRecording every change to a set of files so that any earlier state can be restored, changes can be compared, and several people can work in parallel. Git is the most widely used version-control system; docs-as-code keeps documentation under version control next to the product code.View in glossary → system such as Git or Subversion (or, historically, SourceSafe, discontinued around 2010).

Key principles

Section titled “Key principles”

These systems:

  • Encourage collaboration,
  • Eliminate duplicate copies of files,
  • Reduce the risk of data loss to nearly zero.

For text files, not binary ones, a version control system offers superior functionality:

  • No risk of data loss in the event of network failure,
  • Advanced offline working capabilities,
  • Files are not locked by team members who open them,
  • Very fine-grained restoration capabilities, both in terms of the time since the file was last committed to the RepositoryThe place where a documentation team keeps its sources: shared folders, a CMS database, or a version-control system such as Git, which also stores the complete history of every file.View in glossary → and in terms of workload.
Version history on the trunkGit-style graph of the trunk showing a sequence of commits, with two of them tagged as published versions.version 1version 2

The version control system keeps a history of changes.

Graphical user interfaces now allow these tools, initially designed for command-line use, to be accessed directly through file managers. However, the paradigm on which they are based can be challenging to understand for less technologically inclined users.

Source management systems use the following concepts:

Trunk

Main repository holding all versions of files submitted over time by the technical writer (or more frequently, the developer).

Branch

Secondary repository created from the main version of the source code.

Tag

A snapshot of the trunk or branch at a given time, allowing you to easily freeze a version, such as the published version, and create an archive.

Improper use of version management systems can result in data loss, but with the appropriate level of effort and skill, the risk is significantly lower if the technical writer handles text files under a version manager rather than binary files on a shared directory.

Source code management systems have a proven track record of reliability, managing millions of lines of code. They evolve slowly, adhering to a conservative policy, and are only released for production after thorough debugging, like file systems (Ext4, Btrfs, etc.). If the largest IT development projects, such as GNU/Linux, trust them, why not also use them for technical documentation? Integrating documentation into development processes describes exactly this approach.

Trade-offs

Section titled “Trade-offs”

One drawback, though: these tools are not specifically designed for the XML format and perform line-by-line comparisons between files rather than node-by-node comparisons, which can unnecessarily increase conflicts between commits or branches.

Section titled “Related articles”
Section titled “Related reading”