Version management systems - rustic but reliable
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 control system such as Git, Subversion, or SourceSafe.
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 repository and in terms of workload.
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:
| Element | Description |
|---|---|
| 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?
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.
Additional resources