Define document variants to enable viewing and publishing of conditional content.
Variants let you define content that is only shown under specific conditions. This is particularly helpful when you want to control the scope of content that gets published.
When a variant is selected for publishing with other Scroll apps, only the content that matches the set variant rules will be displayed. This enables you to deliver more relevant documentation based on your audience or variant of your product.
What are Variants?
A variant is a scoped documentation page tree. Instead of including all pages of your page tree, it only includes content that is specific to the variant (e.g. a target audience or product type).
Variants are defined per document and you can set up as many variants for one document as you need. A variant consists of a Variant Name and matching Variant Rules.
Creating a variant is the pre-requisite to start conditionalizing the content in your document.
Why Manage Variants?
When you define variants, the pages that belong to different variants remain in the same documentation page tree. Managing variants is therefore fundamentally different to managing versions, where the pages for each version live in separate page trees.
Keeping pages together in one page tree makes special sense when the content across different variants (e.g. across target audiences or product types) is mostly the same:
It’s easier to manage content when it lives together in one place;
It creates less management overhead when there is only one Confluence page for each piece of content that is common across all variants.
Use variants when the sets of documentation that you want to deliver has more content in common than content that differs.
If you manage two sets of documentation that have little content in common, instead of using variants, consider creating two separate documents. In that case, manage overlapping content with the Include existing page feature of Scroll Document’s Organize Page Tree option.
Example: Define content for two different audiences
Let’s say we have a document called Product Guide. The guide helps users of our product get started and learn how to make best use of the product.
The product itself is used by both end-users and developers, who have different levels of technical knowledge and who intend to use the product differently.
The product guide includes an introduction to the product and covers its most important features:
While most of the content in our product guide is helpful for both audiences, there are also parts that are only relevant for end-users or for developers.
Defining document variants enables us to scope the product guide so that when we publish it, our users end up with only the content that is meant for them. For example, we could achieve the following:
Deliver the section Custom Development only to developers.
Deliver the page Data Aggregation 101 (included in the section Data Aggregation) only to end-users.
Deliver the fragment Get to Know Our Developer Resources on the Getting Started page only to developers.
While each group ends up receiving a set of documentation that is specific to their needs, behind the scenes in Confluence, we are still keeping all the content together. This makes locating and managing the content for us and our team much easier.
Before you begin
To unlock the full potential of the variants functionality, you’ll need to buy the extension app Variants for Scroll Documents. Try it free from the marketplace.
Without the extension app, you’ll find the following limitations:
You can define a maximum of two variants in your Confluence instance
You can’t add, edit or delete page labels in your page tree in bulk
You can’t set up additional rules under a variant rules (nested rules)