Creating and managing versioned documentation for web application, mobile apps and software products is challenging. If multiple versions of the software can be used at the same time, the documentation must be available for all versions. Keeping them updated and in sync is tedious job.
What is documentation versioning?
Creating multiple versions of the software docs is normal. Whenever a (big) new release of the software is published, the software documentation must be updated and published. Typically this document gets a new version number or specifies the related software version. The document related to the current version is published and made available e.g. on the product website, internal help or hosted documentation tool.
Normally, the manuals of the previous version are removed from the download page. But if multiple software version are officially supported, also the documentation must be available for the earlier versions.
Why is versioning of software documentation hard?
Imagine, for the main releases 1.x, 2.x and this year’s 3.x release, the documentation must be available. For the releases 1.x and 2.x, only minor updates and regulatory improvements are made. The current main release 3.x also gets new features and UI screens.
For software development, the code for the main releases 1.x, 2.x and 3.x is stored in different branches. Changes can be (more or less) automatically be merged and compared.
But for software documentation with different documents, this is typically not easy. Imagine, the documentation for release 1.x consists of only a 20 page Word document. Release 2.x was big and now has 5 Word documents with over 200 pages. Release 3.x is now managed in a documentation suite that has more than 200 pages, with new screenshots. Since the next major release will be going international, the plan is to translate the content also in two additional languages. Keeping up with 4 different levels of versioned documentation will be challenging.
How can software documentation be versionized?
Adding and tagging document with a version number is common practice. This can be simple as
- just adding a number to the file name: product_document_1.pdf, product_document_2.pdf
- using additional “flags” as e.g. x for a draft and v for the final release as e.g. product_document_x1.pdf for draft and product_document_v1.pdf for the final version
- keeping the document version the same as the software artifacts version: product_document_v1.3.pdf for release 1.3
- using semantic versioning (common practice for software development, using a 3-part version scheme with 1st digit = major version (and often introducing big changes that are not backward compatible), 2nd digit = minor release (adding new features that are backward compatible), 3rd digit = bugfix release (only fixing existing code, not adding new functionality)
- there are probably a lot more options to manage versioned documentation of web apps and programs
Versioned documentation following semantic versioning
Assuming, the product development teams is using the semantic versioning, the documentation team could follow this approach:
– For major and minor version (1.*, 1.2.*), the software documentation is updated with the every new release
– For bugfix releases (1.2.3), the software documentation is not updated by default – only if the fixed bugs are related to documented features.
What are best practices for versioned documentation?
– For a SaaS or mobile application, there is typically only one “latest” version. So there is only one version of the documentation following the latest release.
– Older version of the user manual should only be kept and provided to the user if the product release is still officially supported and used. Different version of the docs should otherwise not be provided to the user, to not confuse them.
– If your development department uses continuous integration ( CI/CD ), check if the documentation can be integrated into the deployment process. The advantage is that the documentation is always updated and deployed along the latest version.
– If possible, only support and update the latest documentation version. Managing and keeping multiple documentation branches is very hard. If multiple releases of the docs must be managed, only “bugfix” the old releases docs.
What document versioning systems can be used to manage versioned docs?
The open source product ReadTheDocs provide a broad set of features to generate documentation from the software code repository. It handles multiple versions of documentation – using the branches or tags of the repository (git, svn and other). It uses the tools Sphinx and MkDocs internally.
GitBook is a more recent SaaS based tool that focuses on developers to quickly publish the documentation from their git repository – now “building the future of knowledge management”.
Need help in document versioning?
If you have a question or need some more information how perform troubleshooting or create a great troubleshooting guide, reach out to us. Subscribe to our newsletter to get more information and content about documentation processes and best practices.