Two options for handling variants of similar content are to display varying content in the same space, or in different spaces.
To look at these two approaches, consider this example: your team writes a documentation guide for users of your product and a guide for administrators. For each type of person, you write different overviews, steps, etc. to meet their needs. So you're writing a user and administrator variant.
Publish Variants to One Space
You can use expand macros to hide content variations by default. This approach is simple to do and viable in situations where you have a small amount of documentation with little content variation.
Here are a few ways you could implement this approach:
- Create a page for each variation within one space separating variants by page title. For example, the pages could be titled: "Getting Started - User" and "Getting Started - Admin"
- Create a section for each variation within one page separating variants by section. For example, the headings on the page could be: "Getting Started - User" and "Getting Started - Admin"
- Add one or more Expand Macros with varied content on the page. Title the Expand macro(s) to designate for which variation it's intended. For example, the content on the "Getting Started" page is targeted at users and the Expand macro is titled "Additional Information for Administrators"
Keep in mind
- Reduced content and navigation skimability
- Increased documentation overhead, as you'll have to copy shared content to ensure it's updated between all variants or ensure visible and hidden content is updated and makes sense together
- With the expand macro approach, users of less used variants must pay very close attention to find and expand the additional content
Publish Variants to Different Spaces
To separate different variants of your documentation, you could use multiple spaces to publish the variations separately. From each space, you can publish exported documentation in specific variations and have different help site URLs for each variant. This provides a better experience for users than keeping all variants in one space, since they only see content related to their use case.
To implement this approach, you could create the content for all variants in one space. In the example, you would have a "Getting Started" page for users and a "Getting Started" page for admins. On each page, you add a label designating the variant to which it relates. When it's time to publish the content, copy the entire space to multiple spaces, each named for a different variant. Finally, go through each space deleting those pages with labels that don't pertain to the given variant.
Keep in mind
- Increased documentation overhead, as you'll have to ensure content is updated for multiple variants within separate pages
- Potentially lengthy publishing process because of the number of spaces you will need to manually create and modify
- In the case of a help site, this approach may lead to down time because you will have to delete all existing variant spaces to create new ones with the same URLs
Hide Content on Each Page