Using branches in source management systems
Use Git branches to manage parallel documentation projects, product variants, and translation workflows without conflicts - a practical guide for technical writers.
Definition
Section titled “Definition”Source management systems offer the option of creating branches for a project. If a project splits into two incompatible projects, a BranchA parallel line of work in a version-control system: changes made on a branch stay isolated until they are reviewed and merged back into the main line, so several writers, releases or languages can progress at the same time.View in glossary → is created from the main project. This allows the technical writer to manage various translations of technical documentation.
Key principles
Section titled “Key principles”In theory, the branch system can be used to manage:
- different translations of technical documentation
- different variations of the same technical documentation
Variations: prefer conditional text
Section titled “Variations: prefer conditional text”In practice, however, it is preferable to manage variations of the same documentation using section sharing and Conditional textContent marked as applying only to a given audience, product version, or output, so that one source can be filtered at build time into different deliverables. DITA XML implements it with ditaval files; template engines such as Jinja do the same for text formats.View in glossary → filtering mechanisms provided by documentation tools.
Translations: it depends on the system
Section titled “Translations: it depends on the system”On the other hand, the branch management system is more or less suited for managing translations, depending on the source control system used.
The main difference between Git and Subversion is the way they handle branches. Creating a branch in Subversion is equivalent to duplicating a directory. The files in these directories then evolve independently. In Git, however, branches can be created without duplicating data. Within the same local directory, you can use a command to switch between branches.
Translations: copy or branch?
Section titled “Translations: copy or branch?”Creating a translation of documentation involves forking or branching from the initial document. When using Git, the options are:
- Copy the source language directory
- Create a branch from the source language directory
In theory, branching allows for cherry-picking and makes it easier to apply changes affecting only the project’s XML code to all target languages.
Examples
Section titled “Examples”For example, a change from:
<image href="filter.png" placement="break"/>to
<image href="filter.png" placement="break" scalefit="yes"/>in the English version of the documentation can easily be applied to the Chinese, French, German, or other versions if it has been committed separately. In practice, this operation can be complex and is only useful if managing a large number of different language versions. Nevertheless, the branch solution allows such operations, while the directory solution does not. However, it is more challenging for the technical writing team to understand and use.
Additional resources