Skip to main content

Structure your site for product versioning

Written by James Valent
Director of Support at MindTouch
This page applies to:MindTouch Responsive

If you have (or will have) various versions of your product, you need to consider how to handle documentation for versioning.

What is the best way to structure around versions?

There are two ways to approach your content structure: version-centric or version-agnostic. Both approaches have their advantages. Before deciding on an approach, consider your use case:

  • Are your product versions vastly different from one another? Is most of your documentation unique to your versions? Do you only have little shared content across product versions? If so, version-centric structuring may be your best approach. 
  • If, on the other hand, do you only have one version or product? Or do versions of your product contains only small feature differences? In that case a version-agnostic approach will provide a cleaner experience for you and your end users.

Which approach is best for my product?

Version-centric structuring

If you want your users to be able to choose content for a specific version of your product, consider version-centric structuring. With version-centric structuring, you will nest second-level categories for your versions directly underneath your product category. From there, follow the standard structure of guides and articles in each version hierarchy.

Topics (which are technically articles) provide an additional layer of organization but are not mandatory to maintain the health of your structure. 

Version-agnostic structuring

The alternate approach, version-agnostic structuring, focuses on the general main features of a product and then separates out articles that pertain to a specific version. For this approach you will have to use a custom classification to display version-specific articles in your guides (see next section). For version-agnostic structuring, the standard Category > Guide > Article organization will work just fine.

Topics (which are technically articles) provide an additional layer of organization but are not mandatory to maintain the health of your structure. 

How to implement a version-agnostic structure

Let's say most of your documentation applies globally to all your product versions, but you also have documentation that applies only to Version 1.0 or Version 2.0. To version your content via the version-agnostic approach, you would first create a custom classification labeled "Version" with the options "Version 1.0" and "Version 2.0."


As you add articles, you would assign the appropriate classification in the pages settings. Finally, you would add the classification tabs "Version 1.0" and "Version 2.0" under which your version-specific articles would be displayed, while the rest of the guide content would apply to all  product versions. 


Benefits of each structure

Structure  Benefits Limitations

Less customer effort to self-service as there is content to drill into.

Cleanly separates content versions along side general product guide.

May be harder to work with for those products which have major changes between versions

Best if you have only a few articles for each version in a guide tab.

Users may not be aware of the different version documentation until they are in the guide and may overlook the tabs. Will have to prominently alert users to the various versions in the guide tab. 


Allows users to quickly drill down to find their specific product version.

Your versions are given prominence right of the bat.

If there is little or no shared content between versions, your maintenance of duplicate content is minimal.

More overhead for documentation management for large shared content.

Potential for duplicate articles; can have an effect on search engine optimization.

More content to drill into means a potential reduction in ticket deflection.

A search bar on the product page will provide search results for all versions. Will have to guide your users on how to filter search results on the results page for specific versions or consider hiding the search bar on your product page. 


What if an article applies to multiple versions?

Read our article on duplicating content without hurting your SEO. You may also want to review how to add a version banner to your article.

  • Was this article helpful?