Skip to main content
Skip table of contents

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:

Displays Variant Manager dialog

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:

  1. Click Scroll Documents from the Apps section in your space sidebar.

  2. From the Document Library, click the document card of a document.

Or

  1. From a page in a document, click Document toolbox.

  2. 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:

  1. Within the Document Manager, select Manage > Variants, this will take you to the variant manager.

  2. Click New variant.

  3. Give the variant a name such as “User Guide Cloud.”

  4. Under “Rules,” set the first dropdown to all so it says: “Include pages that match all of the following rules.”

  5. Next to the has label dropdown, add the label “var-cloud.”

    Displays New Variant Dialog
  6. Hold the Alt/Option key while clicking Add a rule ➕, this will create your first section of nested rules.

  7. Set the new dropdown to all so it says: “all of the following rules are true.”

  8. Set the second label dropdown to does not have label.

  9. Add the label “var-admin” to make sure pages relevant only to the admin group do not appear for users.

    Displays New Variant Dialog
  10. Click Add a rule ➕ next to the dropdown saying “all of the following are true” to add a new label rule.

    Displays Variant Details
  11. Set the new label dropdown to does not have label.

  12. Add the label “var-dev” to ensure pages relevant to the dev group do not appear for users.

  13. Click Refresh 🔄 to update the preview, you should now see the pages: “WiseApp Introduction”, and “WiseApp Cloud Users”.

  14. Click Save when you are done.

    Displays Variant details

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.”

Displays Variant details

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:

  1. Click New variant.

  2. Give the variant a name such as “Admin Guide Cloud.”

  3. Under “Rules,” set the first dropdown to all so it says: “Include pages that match all of the following rules.”

  4. Set the label dropdown to has label.

  5. Next to the has label dropdown, add the label “var-cloud.”

    Displays New Variant dialog
  6. Hold the Alt/Option key while clicking Add a rule ➕, this will create your first section of nested rules.

  7. Set the new dropdown to any so it says: “any of the following rules are true.”

  8. Set the label dropdown to has label.

  9. Add the label “var-admin” to make sure pages relevant to the admin group appear.

    (info) 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.

    Displays variant detail with a var-admin
  10. 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.

    Displays Variant Details to create an additional nested rule

  11. Set the new dropdown to all so it says: “all of the following rules are true.”

  12. Set the label dropdown to does not have label.

  13. Add the label “var-admin” to make sure the pages relevant for users appears for the admin group.

    (info) 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.

    Displays variant details dialog
  14. Click Add a rule ➕ again next to the dropdown “all of the following are true” to create a new label rule.

    Displays variant detail dialog
  15. Set the label dropdown to does not have label.

  16. Add the label “var-dev”, this is also part of the process to ensure that pages relevant for users appear for the admin group.

    Displays Variant details dialog
  17. Click Refresh 🔄 to update the preview, you should now see the pages: “WiseApp Introduction”, “WiseApp Cloud Users”, and “WiseApp Cloud Admin.”

  18. Click Save when you are done.

    Displays Variant details dialog

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.”

Displays Variant details dialog

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.”

    Displays variant details dialog
  • In the variant Dev Guide Data Center: “WiseApp Introduction”, “WiseApp Data Center Users”, and “WiseApp Data Center Dev.”

    Displays variant details dialog

Congratulations!

You have successfully set up a collection of nested variant rules.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.