: How to Document Systems with Different Versions? Scenario I need to create and maintain a user documentation for a system of which there are different instances in use by different target groups.

Vote Up Vote Down

The method Splunk uses for their documentation is to use a per-version structure (though oftentimes the doc is the same for two different versions of the tool), and allow the reader to pick which version they want to read.

So you might be looking at 7.0.2, or 6.5.1, or 6.2.3, or any other possible version.

The URLs look like the following:
docs.splunk.com/Documentation/Splunk/7.0.2/Knowledge/Configurecalculatedfieldswithprops.conf http://docs.splunk.com/Documentation/Splunk/6.5.1/Knowledge/Configurecalculatedfieldswithprops.conf docs.splunk.com/Documentation/Splunk/6.2.3/Knowledge/Configurecalculatedfieldswithprops.conf

While I don't know what powers their system under the hood, I do know the doc team publishes docs for new versions when new versions release. And that old versions' docs are kept around more-or-less forever.

(0)

Vote Up Vote Down

What kind of software do you use for content development? I've found that branching is a good way to address version control if you have a need to support multiple versions simultaneously, but you would need a Content Management System (CMS) or authoring tool that has this type of functionality. You also need to consider how the information is delivered and whether that system has the functionality you need.

With branching, you can create, edit, and manage different versions of content in parallel. For example, you might edit the current version, let's call it 1.0, in a master branch. Once you've released your content for v 1.0 you would branch that content. This basically involves making an exact copy of the publication. Then, you can edit in the master branch to develop content for v 1.1, while still maintaining v 1.0 separately. You can also publish each version to provide accurate support to your end users for those versions.

Additionally, if you have a need to publish different content for different audiences, you might consider using conditional processing. For example, if you need to publish certain content on "testing" features for an internal audience only, you could tag those features "internal" or "testing" and filter the published content accordingly to include or
not include that content. Similarly, you could conditionalize content for integrations, specific audiences, etc.

I work in a DITA CMS that has all these functionalities, so again, you would need to have a system or systems that can support these functions.

(0)