Choose when to create content from the primary or variant object

Object Variants

Acme's requirements

Each release involves some amount of new or updated content. To save time, the authors want to start with the content that will require the least amount of work to update.

Solution

When using variants, decide whether you create your new content from the primary object or any of its variants.

  • Create the variant from the primary topic when its content is easy to update for the new release.
  • If any of the existing variants offer a better starting point, then create the new content from a variant.

Follow the same process no matter which option you decide on. Select the object you want to create a variant from, assign the "release" variant criteria, then modify the variant topic's content.

Choosing the starting point

When should you choose the primary object or one of its variants as the starting point for updating content?

Example where you may start from a variant topic: you have a primary topic for a function. Major changes were made to the functionality in the following release and a variant topic was created to document these. As a result, the content in the primary topic and the variant topic are now very different. The latest release adds another minor update to the variant functionality - in this case the best starting point is the variant topic.

Example where you may start from the primary topic: the most recent update is a variant created for a branched build for a particular customer. The variant contains changes for that customer, and will never be used for general releases. For your next general release change, the better starting point is the primary topic as it is much closer aligned to the general release content and will be easier to update for the next general release.

To create content from the primary or variant object:

  1. Choose the topic that will be your starting point (the easiest point from which to update).
  2. Create a variant of that topic from any of these options:
    • An ordinary topic with no variant "children" and no variant criteria assigned
    • A primary topic that either has variant "children" or variant criteria assigned
    • Another variant topic
  3. Update the content in the variant topic. As each variant object is a unique object, just freely modify the content and headings. If you are using Context IDs to link into your Help files, then the Context ID from the primary object is copied over and used, unless you manually update it in the variant object.

Variant relationships

When you create a variant object from a primary object, an association is created between the two objects. This association provides the information required to swap the parent object with the variant object when filtering is applied to the book or publishing job.

When you create a variant from an ordinary object, the ordinary object is converted to a primary object.

When you create a variant from another variant, the association is still created between the new variant object and the group's primary object, because the association must always point back to the group's primary object to enable filtering.