Create and Manage Modular Product Manuals in Confluence
When your products are built with different modules, your product documentation needs to reflect each configuration you build. Imagine you are building satellites: satellite “Alpha” uses the earlier versions of the the Solar cells and Communication system modules, while satellite “Delta” uses later versions. How do you create separate, accurate documentation for each satellite without starting from scratch every time?
This is where Confluence and Scroll Documents come in. If you're managing your documentation in Confluence, you can use Scroll Documents to create, manage, and publish flexible product documentations for your multi-module products.
This guide shows you how to use Confluence and Scroll Documents to create and manage module documentation, as well as how to combine versions of each module into a product-specific user manual.
Understand Modular Documentation
Before we dive in, let's clarify what modular documentation is, what it isn’t, when it's useful, and how it works.
It's important to note that "modular documentation" can be defined in many ways. In this article, we use the following definitions and interpretations.
What it is (and what it isn't)
This section clarifies how we define and differentiate modular documentation, variant management, and content reuse. We'll be using our own working definitions, so keep in mind that other interpretations may exist.
We find it’s important to distinguish between these approaches, as we have found they serve different purposes and can get mixed up:
Content reuse: Content reuse is a strategy to reuse smaller chunks of content across multiple pages. In Confluence, you can achieve this by setting up a dedicated include library page tree and using macros like the Include Page and the Insert Excerpt to reuse content. It's often managed in one space and then reused in one or multiple documentations.
Variants (conditional content): Variant management is a feature in Scroll Documents. Variants are managed within one documentation to filter irrelevant parts out. This enables you to filter content for different audiences based on criteria like user groups, payment plans, countries, etc. You can filter entire articles or specific blocks of content within them.
Modular documentation: Modular documentation is a way to manage and combine documentation for products with many parts (modules), like the satellite example we gave earlier. In comparison to variant management, modular documentation uses one documentation per module and combines them into one. Each module needs its own documentation with its own version history. This is common for complex products where each final product is a unique combination of modules.
Why is it helpful?
Modular documentation makes it easy to create and deliver documentation for products with many variations. This is helpful for:
Products that are heavily customized for each customer, like production lines, heavy machinery, or satellites.
Products that are configured by the user, like cars, where customers can customize everything from the engine and paint color to the type of steering wheel.
With modular documentation, you can assemble the appropriate documentation versions for each module, ensuring your final document accurately reflects the product's configuration.
How does it work?
Instead of managing one huge manual containing every product configuration, you create dedicated product documentations for each module. These modules can then be combined in different ways to create custom documentation for various product configurations and audiences.
Let's revisit the satellite example. Imagine satellite Alpha and satellite Delta are built using different versions of the modules: Solar cells and Communication system.
To create accurate documentation, the technical writer needs to ensure each satellite's manual contains the correct module versions.
The figure below illustrates how the product documentation for Alpha and Delta uses the same modules but in different versions:
Product Alpha (Space AL): The documentation for Product Alpha is assembled by combining content from the modules Solar cells (version 1) and Communication system (version 3). In this example, this product uses earlier versions of both modules.
Product Delta (Space DL): The documentation for Product Delta uses later versions of the same modules: Solar cells (version 5) and Communication system (version 7). This product combines these specific versions of the modules to reflect its configuration.
Set Up Your Module Documentation using Confluence and Scroll Documents
With Confluence, you can collaborate with your colleagues on a centralized platform, ensuring authorized team members can access and contribute to the documentation. When you install Scroll Documents, you can add more advanced content management features to Confluence, such as:
Versions: Save versions and keep track of changes to each modules documentation.
Variants: Conditionalize articles and content in your documentation for different audiences.
Languages: Translate your content for international clients.
Publishing: Share your finished docs online, offline, or within Confluence.
When setting up your first modular documentation with the help of Scroll Documents, we recommend:
One Scroll Document per module: For modular products with individual versioning schemes, create a separate Scroll Document for each module.
One space per document: We recommend managing each Scroll Document in its own Confluence space to keep things organized and avoid page title conflicts.
Before you continue reading
New to Scroll Documents? Each module should be managed as its own product documentation. If you haven't started using Scroll Documents to manage your modules, check out our article: Create and Manage Product Documentation in Confluence. This will help you get started.
Ready to combine modules? If you already have modules managed with Scroll Documents and want to learn how to combine them into a single deliverable, continue reading this article.
The next part explains how to publish individual modules into one product-specific user manual, using Scroll Documents Publish to Confluence feature.
Combine Modules Into One Product Manual
When it's time to combine your different modules into a single user manual, Scroll Documents' Publish to Confluence feature can help. Let’s once again revisit the satellite example:
satellite Alpha uses earlier versions of the modules Solar cells and Communication system (V1 and V3).
while satellite Delta uses later versions (V5 and V7).
The technical writer is using Scroll Documents to manage the product documentation for the Solar cells in space "CL" and the product documentation for the Communication system in space "CS." To create the user manuals, they use Publish to Confluence to:
Publish the Solar cells module (V1) and the Communication system module (V3) to the home page of space "AL" for Satellite Alpha's user manual.
Publish the Solar cells module (V5) and the Communication system module (V7) to the "Modules (M)" page in space "DL" for Satellite Delta's user manual.
The published content consists of normal Confluence pages (Scroll Documents is not active in the target spaces). As you see in the example above, you can choose where to publish your modules within the target space:
Publish to the space home page
or a specific parent page deeper in the page tree.
You can also add customer-specific content directly to the target space alongside the published modules. After publishing the writer can also restructure the page order, adds links between the pages, and add the finishing touches before delivering the manual to the customer. However, it’s important to keep the following in mind:
Edit in the source: If you plan to publish updates into this space from the same Scroll Documents, don't make changes to published pages directly in the target space. Instead, make your edits in the source Scroll Document and republish. This prevents your changes from being overwritten.
Maintain separate hierarchies: Keep content from different Scroll Documents in separate hierarchies within the target space.
Deliver The User Manual
When it's time to deliver the documentation, the writer can choose the manual format based on the customer's preference:
Publish within Confluence.
Publish to an authenticated online help center.
Export into a customized offline manual.
To learn more about the recommended publishing, editing, and delivery process, including more detailed information and recommendations for each delivery option, follow the steps below:
When it's time to combine the different module versions into a customized user manual, follow these steps:
Publish: Use Publish to Confluence to publish the desired version, variant, and/or translation of each module to a dedicated target space.
Restrict Access: Apply space permissions to the target space so only authors and editors can see the content while you're working on it.
Structure: Organize the published content within the target space to create a clear and user-friendly manual.
Need to cross-reference between modules? See: Link between Scroll Documents
Deliver: Once you're finished, choose how you want to share the manual:
Within Confluence: Grant view permissions to the target space for internal users.
Online help center: Publish the space as a dedicated Scroll Viewport help center (you can add set view permissions to control access to the site).
Offline manuals: Export the target space to a customized PDF, Word, or HTML file using a Scroll Exporter app.
This process allows you to create and deliver customized user manuals tailored to specific client needs and publishing preferences.