Tutorial: Define and Edit Multiple Variant Rules
With Scroll Documents, users can use multiple nested variant rules to efficiently manage and distribute user documentation to audiences with different needs. This tutorial will walk you through a hypothetical scenario and teach you not only how to set up multiple nested variant rules, but also why you would want to in the first place.
Prerequisite
To follow this tutorial and set up more complex nested rules, you also need to install the extension app Variants for Scroll Documents.
Example Case Using Multiple Nested Rules
You are a technical writer for the software company Good Software and your team has a portfolio of apps, which you are selling to customers.
Customers can choose which apps they want to purchase, and it’s your job to deliver them the relevant user documentation based on their product choice, user groups, and hosting environment. The finished documentation is published to an online help center with the help of Scroll Viewport.
You are currently working on the user documentation for your app WiseApp. There are Cloud and Data Center versions of this app, and the user groups consists of users, administrators, and developers.
In the sections below, we’ll give you a deep dive into how you can set up the user documentation for the app, with its different user groups and hosting environments.
Existing documentation setup
Below is the list of pages in your WiseApp documentation. We've already labeled these pages based on user groups and app deployment to streamline the process of assigning them to their respective variants. While setting up the variants, you can also add labels to pages manually, but we've taken care of this step for the exercises.
The page names have also been adjusted to reflect which variant they should belong to, solely for the purpose of this exercise:
WiseApp Introduction (labels: var-cloud, var-dc)
WiseApp Cloud Users (labels: var-cloud)
WiseApp Cloud Admin (labels: var-cloud, var-admin)
WiseApp Cloud Dev (labels: var-cloud, var-dev)
WiseApp Data Center Users (labels: var-dc)
WiseApp Data Center Admin (labels: var-dc, var-admin)
WiseApp Data Center Dev (labels: var-dc, var-dev)
The labels are needed to map the pages to their relevant variant.
In order for a page to be included in a specific variant, all of its ancestor pages must also belong to that variant. Hence, it is mandatory that the rules for every variant include the top-level page of the page tree.
Setting Up Multiple Variant Rules
When organizing WiseApp documentation for your help center visitors, you have three main goals:
Enable readers to filter relevant pages based on their hosting environment (Cloud or Data Center) and user group (user, admin, or dev).
Ensure that admins and devs can access user documentation when filtering for their user group (as the user documentation is relevant for them as well).
Optimize setup efficiency and maintainability by avoiding unnecessary labels.
To achieve these goals, you have decided to create one variant for each combined case (user group and hosting environment), see screenshot below:
In the next sections, we will walk you through how you could set up each of the listed variants.
Set up the user variants
As a first step, you will create the user variants as the content of these variants should be available for all user groups.
Start with navigating to the Document Manager:
Click Scroll Documents from the Apps section in your space sidebar.
From the Document Library, click the document card of a document.
Or
From a page in a document, click Document toolbox.
Click on the cog icon.
Now, let’s continue with creating your first variant. In this example, we'll start by creating one for users on Cloud:
Within the Document Manager, select Manage > Variants, this will take you to the variant manager.
Click New variant.
Give the variant a name such as “User Guide Cloud.”
Under “Rules,” set the first dropdown to all so it says: “Include pages that match all of the following rules.”
Next to the has label dropdown, add the label “var-cloud.”
Hold the Alt/Option key while clicking Add a rule ➕, this will create your first section of nested rules.
Set the new dropdown to all so it says: “all of the following rules are true.”
Set the second label dropdown to does not have label.
Add the label “var-admin” to make sure pages relevant only to the admin group do not appear for users.
Click Add a rule ➕ next to the dropdown saying “all of the following are true” to add a new label rule.
Set the new label dropdown to does not have label.
Add the label “var-dev” to ensure pages relevant to the dev group do not appear for users.
Click Refresh 🔄 to update the preview, you should now see the pages: “WiseApp Introduction”, and “WiseApp Cloud Users”.
Click Save when you are done.
Repeat these steps when creating the variant for users on Data Center. Just remember to use the variant name “User Guide Data Center” and the label “var-dc” instead of “var-cloud.”
Great!
You have successfully set up your first variant with nested rule sets. Now, let’s continue with creating variants for the admin user groups.
Set up the admin variants
Continuing with the setup of variants for the admin user group on Cloud and Data Center, follow these steps:
Click New variant.
Give the variant a name such as “Admin Guide Cloud.”
Under “Rules,” set the first dropdown to all so it says: “Include pages that match all of the following rules.”
Set the label dropdown to has label.
Next to the has label dropdown, add the label “var-cloud.”
Hold the Alt/Option key while clicking Add a rule ➕, this will create your first section of nested rules.
Set the new dropdown to any so it says: “any of the following rules are true.”
Set the label dropdown to has label.
Add the label “var-admin” to make sure pages relevant to the admin group appear.
Note: As per the screenshot, a message will appear indicating that the page tree is empty due to the root page not being included in the variant. To resolve this warning, we will need to ensure that our variant rule set again includes the root page "WiseApp Introduction." This issue will be addressed in the upcoming steps.
Hold the Alt/Option key while clicking Add a rule ➕ next to your new nested rule “any of the following rules are true.” This will create an additional nested rule.
Set the new dropdown to all so it says: “all of the following rules are true.”
Set the label dropdown to does not have label.
Add the label “var-admin” to make sure the pages relevant for users appears for the admin group.
Note: Implementing the rule "all of the following are true" includes pages without "var-admin", while still maintaining the rule “has label var-cloud”, ensures that the root page "WiseApp Introduction" is included in the variant rule set again, resolving the warning about an empty page tree.
Click Add a rule ➕ again next to the dropdown “all of the following are true” to create a new label rule.
Set the label dropdown to does not have label.
Add the label “var-dev”, this is also part of the process to ensure that pages relevant for users appear for the admin group.
Click Refresh 🔄 to update the preview, you should now see the pages: “WiseApp Introduction”, “WiseApp Cloud Users”, and “WiseApp Cloud Admin.”
Click Save when you are done.
Repeat these steps when creating the variant for admin users on Data Center. Just remember to use the variant name “Admin Guide Data Center” and the label “var-dc” instead of “var-cloud.”
Set up the dev variants
Repeat the process you followed for the admin variants. Just keep the following in mind:
Use the variant names “Dev Guide Cloud” and “Dev Guide Data Center.”
Additionally, use the label “var-dc” instead of “var-cloud” and “var-dev” instead of “var-admin” when configuring the rule to ensure the relevant pages for developers appear.
After refreshing the dialogs you should now see the following pages:
In the variant Dev Guide Cloud: “WiseApp Introduction”, “WiseApp Cloud Users”, and “WiseApp Cloud Dev.”
In the variant Dev Guide Data Center: “WiseApp Introduction”, “WiseApp Data Center Users”, and “WiseApp Data Center Dev.”
Congratulations!
You have successfully set up a collection of nested variant rules.