How do you document software with multiple versions?

Firstly, managing the complexity of multiple software versions is crucial. Documentation helps ensure that each version adheres to standards and requirements, minimizing inconsistencies and compatibility issues. Secondly, informing users and customers about the features, benefits, and limitations of each version is critical for their decision-making process. Lastly, documentation plays a vital role in issue tracking and support. It enables developers to record and address issues, bugs, and user feedback for each version systematically. Timely and accurate support and updates can be provided, enhancing the software's reliability and user trust.

Often times, libraries provided by the operating system's package manager are not the latest versions. Sometimes they are several versions behind. Without versioning the documentation it's impossible to know what the correct way to do something is in the specific version you have to use.

Simply, to document multiple versions in line with our preferences, use a Version Control System (VCS) to manage code and documentation, and employ a documentation generator like Doxygen or Sphinx. Choose a documentation framework or platform such as ReadTheDocs and establish a documentation standard. Maintain separate documentation for each version, including version-specific release notes, clear version navigation, and user-friendly URLs. Ensure testing, automated deployment, and a feedback mechanism are in place for consistent and user-friendly documentation.

Ensure each version's documentation includes version number and name, clear installation and configuration instructions, comprehensive feature descriptions, a changelog outlining changes in each version, troubleshooting guidance, support and update policies, and references to additional resources and support channels. Maintain a consistent version numbering scheme, provide practical usage examples, and specify any deprecated features. This approach ensures clarity, consistency, and user-friendly documentation.

Often the documentation between versions doesn't change much. Maybe there are some small API changes or a couple of new best practices are added. However, from time to time there are major changes in a library that also require major rework in the documentation. The version number of the docs should match the one of the code. A changelog is really helpful to understand changes compared to the last version. If you are good with commit messages a lot of this can be automated by version control systems.

In one of my former projects we added really basic analytics to the documentation. The main goal was to understand which pages where relevant to the user and which weren't. Surprisingly, most people went straight to the examples and didn't spend any time on the quick start guide.

Maintain a Changelog file within your project repository. It should include a chronological list of changes for each version, including features, bug fixes, and any other relevant information Create release notes for each version that provide a concise summary of what's new, what's changed, and what's fixed.

Consider online documentation platforms like Read the Docs or Swagger for API documentation. These platforms allow you to easily maintain and publish version-specific documentation.