Create and Manage Product Documentation in Confluence

Trying to figure out if Confluence has what it takes to manage your product documentation? Looking for guidance on where to start with any of the Scroll apps for Confluence? Well, you’ve come to the right place.

If any of the following points sound familiar, this article will help you move forward with your product docs:

• You use Confluence as a team collaboration hub and would like to also collaboratively manage your product documentation.

• You need to manage multiple versions, variants, or translations of your documentation.

• You need your documentation to be readily available to your users, whether that’s on the web, a mobile device, or in formats like PDF or Word documents.

It’s all possible with Confluence and Scroll.

In fact, the article you’re reading right now was written in Confluence and published to this help center with the Scroll apps. It’s just one of the many examples of how you can manage and publish documentation in Confluence, and this article will help you create the ideal setup for your team.

To give you an idea of what’s possible, here are some more examples of help centers created with Confluence and Scroll:

Set up Your First Documentation

In this section you’ll learn about which options to consider when setting up your document. You’ll also get an introduction to Scroll Documents’ versioning functionality.

Establish your working version

The very first step in setting up your documentation is to establish a Working version. You can think of the Working version as the continuously progressing version of your documentation, which is where you make changes to your content and create new pages.

There are two ways to establish your working version:

• Use existing page tree

• Create new page tree

Which one makes most sense for you will depend on whether you will be writing your documentation from scratch or already have content in place that you’d like to start managing with Scroll Documents.

Use existing page tree

You can establish these pages as your Working version and start managing your documentation from there. To do that, simply select the root page of your existing documentation in the Use existing page tree option when creating your document, or navigate to the root page directly and enable Scroll Documents from the Document toolbox.

Create new page tree

When creating a new page tree, you’ll have a couple options:

• Create from template: Use the bundled product documentation template that puts in place a page structure that you can then adjust to your needs.

• Create your own structure: Use the Organize page tree tool to quickly create many pages and structure them as you see fit.

The page tree you set up here will become the Working version of your document and serve as the basis for all future versions of your documentation.

Save versions of your documentation

A saved version is a snapshot of the pages in your Working version. In other words, when you click Save a version you will copy the page tree from the Working version. The saved version can be managed, edited, or published separately from the Working version.

When saving versions, these are saved within the space your document is in by default. The pages will be added under a new parent page named “Versions of <Document Title>” which you also can rename to whatever you prefer.

The purpose of the Save a version feature is to enable you to manage and release versioned documentation in different ways, for example:

• If you are documenting a SaaS product, it’s likely you only want to maintain and publish one single version at a time. With Scroll Documents, you can always work on the most recent version in private without affecting the already published version.

• If you are documenting an on-premise product, Scroll Documents enables you to work on and publish multiple versions at the same time. That way users who are still using an older version of your product will have access to the right documentation for them.

Author and Review New Content

Scroll Documents offers several features that will help you manage an authoring and review process. In this section, you will learn more about how to author and review content with the features available in Scroll Documents.

Authoring

As you learned previously, the purpose of the Working version is to use it as a continuously progressing version for updating and creating pages.

Whether you are a single content author or a team of several authors, you probably want to make sure new pages and changes are made only in the Working version. To achieve this, you can add edit restrictions to already saved versions to prevent accidental changes in the wrong version.

For each version of your document there is a Manage restrictions feature available in the shape of a padlock. In the Manage restrictions dialog, you can define which users or groups are allowed to view and edit pages in the saved version.

Review

When it’s time for review, the reviewer can use the Compare versions functionality to see which pages were added, deleted, or modified between two versions, thus requiring the reviewer’s attention. Modified pages can be viewed in a side-by-side diff view to visualize all changes to the page content.

When the review is complete, the reviewer can save a new version from the Working version. After saving the new version, the reviewer can also “freeze” the version by adding edit restrictions to it which will prevent new changes from being made to the newly-saved version.

Track changes

While authoring and reviewing your documentation, it’s likely you and your team will recommend changes or edits as comments on your pages.

To keep track of the changes and comments in the Working version, you can make use of the following features:

• View activity - See what has been commented, created, and updated in the documentation version.

• Compare versions - Perform a page-by-page comparison on a paragraph level to see what has changed between two versions.

Author Content for Specific Audiences

Does your product have a varied user base or a big global audience? In these cases, you might also have the need to adapt or translate your content for this broad audience.

In addition to versioning, Scroll Documents can also be used to translate or create variants of your document. These functionalities are delivered by the two extension apps:

• Translations for Scroll Documents

• Variants for Scroll Documents

Translate content

If you have an international audience and a need to manage your product content in different languages, you can make use of Translations for Scroll Documents. This extension enables you to add languages to you document and translate its saved versions.

You can define an authoring language and add additional languages which the content should be translated into.

When the Working version has been reviewed and approved, you should save a new version of your document. We recommend you add translations to the newly-saved version.

The translation can be added to the saved version through:

• A translator directly within Confluence

• An XLIFF-based workflow where you import files translated by a translation agency

Conditionalize articles and text

Let’s say your product has different feature tiers or subscription plans. For this reason there might be some articles or page content that apply only to specific audiences. Instead of managing multiple documentations you can make certain pages or paragraphs conditional.

With Variants for Scroll Documents you can have a variant for each audience. You can define label-based conditions for pages or paragraphs to be included in a given variant. When it’s time to release the documentation you can choose between:

• making one or multiple variants available in a Viewport help center,

• or export a selected variant to PDF, Word, or HTML format

Publish and Release Your Documentation

As we mentioned in the beginning, this product documentation use case is a part of a larger Scroll documentation solution for Confluence. Scroll Documents takes care of the content management part, whereas the publishing part involves Scroll Viewport and the Scroll Exporter apps.

Publish to a help center

Scroll Viewport allows you to publish your product documentation as an online help center, which can be publicly available or restricted through authenticated access.

When publishing to Scroll Viewport you have the following options:

• One site, multiple versions – Publishing multiple versions of your documentation gives readers of the help center the option to switch between versions using a version picker.

• Multiple languages or variants – When publishing translated documents or a document with variants, you’re free to either give users access to a language or variant picker or spin up a dedicated site for each language or audience.

• Documentation portal – When publishing multiple Scroll Documents to a help center, a portal page will be created where the user can browse the documentation for the different products or search all documentations.

Publish as an offline user manual

With the Scroll Exporter apps you can export your product documentation into offline user manuals. You can choose whether you want to export your user manuals into:

• PDF format with Scroll PDF Exporter

• a Word document with Scroll Word Exporter

• an HTML file with Scroll HTML Exporter

When exporting your user manual you can choose which combination of version, language, or variant you want to export.