Variants vs versions

Object Variants

Variants and versions provide different options for working with changes to documentation.


Use variants when you need to maintain multiple adaptations of your content based on different criteria. For example, adaptations based on location (country or state), product, and platform. For example, you can have three variants of a topic in a book, and the one that is used at any time depends on the specific filter. You also use variants of embedded topics to add "conditional text" to a topic.

Variant objects are linked to a book through their primary object. The primary objects are swapped with the appropriate variants when you filter or publish the book.

Tip When you create multiple variants from an object consider updating the variant object's description (on the General tab in the object's properties). This will make it easier to identify a specific variant in the object list.


The purpose of version control is to allow you to create new versions of an object, but still retain the original. How and when you use them is really up to you. The most common use for them is creating proposed changes to an object - you can create a new version of an object, and then when you're happy with it, replace the old version with the new one in all relationships. You can revert back to an old version at any time, by replacing the versions again.

Using versions with variants

On rare occasions you may need to combine the functionality of version control with variants. As an example, this happens if you are preparing changes to a primary topic, but the changes are not ready for release yet. To deal with this situation you'll need to do the following:

  1. Create a new version of your primary object, then make and save your changes.

  2. Create your variant objects for that version of the primary object.

There are a few things to be aware of if you do combine the functionality:

  • Only primary objects use version control. Versions are not created from variant objects.

  • Each version of the primary object requires its own set of variant objects.

  • The active version of the primary object has the relationship to the book.

  • Book filtering and publishing use the variants created from the active version of the primary object.