Having the right tool to document and share your company’s policies, processes, and handbooks can make all the difference for your organization. To keep your organization running smoothly, this content should be readily available to your team and always up-to-date.
Between its collaborative features and its ease of use and access, Confluence offers the perfect base for creating and centralizing these resources. When managed in Confluence, you can keep all resources in one place as an internal knowledge base. These include:
Operating procedures, and more.
Manage Internal Documentation in Confluence with Scroll Documents
In this article, you’ll learn how to better manage your company documentation in Confluence with Scroll Documents. Using the example of an employee handbook, you’ll learn how features like versioning, variants, and translation management can be used to manage and deliver content that is consistently up-to-date and relevant for everyone across the organization.
Confluence becomes an even better tool for your internal resources when you introduce Scroll Documents to your internal documentation workflow. With Confluence alone, you can manage a single version of your documentation, whereas with Scroll Documents you can manage changes across versions. For legal or just educational reasons, you may also need to keep record of what was previously documented and when, which Scroll Documents also helps you keep track of.
With additional features like activity tracking and read requests, you’ll be able to track changes to your content over time and ensure your team has read and understood any new updates.
This article focuses on the setup process for your internal documentation with Scroll Documents, but will also cover the publishing options available to you. If you haven’t already, we recommend installing a few additional Scroll apps depending on your publishing requirements:
Set Up an Internal Documentation
In this section, you’ll learn about what to consider when setting up your Scroll Document. You’ll also learn about the purpose of Scroll Documents' Working version.
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.
If you already have several versions of documentation which you want to import as separate versions in your document, you can use the feature Add existing page tree for this. To learn more we recommend reading: Assemble Several Spaces into One Document
Use existing page tree
Use existing page tree is a good option if you already have all pages of your handbook created and assembled under the same parent page.
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.
Selecting the topmost page in a space (usually the space home page) as the root page for your document will effectively treat the whole space as the Working version of your documentation.
While not required, it makes things simpler and is the recommended approach. Just keep in mind that all pages in that space will be part of your documentation.
Create new page tree
Creating a new page tree is the better option if you want to create a handbook with a new page tree structure that you can define and customize. You can create brand new pages or reuse existing pages from anywhere in Confluence.
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.
When creating a new page tree structure using Organize page tree, you’ll have the options to Copy or Include content from existing pages into new pages. If the content on the new page should be independent form the source page choose Copy, whereas if the content always should match the source page choose Include. To learn more read: Organize Page Tree
Save and Manage Versions of Your Documentation
In this section you’ll get more familiar with how versioning works in Scroll Documents. You’ll also learn how to:
Manage different versions of your employee handbook.
Keep track of changes and comments during the authoring process.
Save a version
With Scroll Documents, you can define/save multiple versions of your employee handbook in Confluence. When you add versioning to your documentation you enable your team:
To author upcoming versions of your documentation in private without touching already saved/released versions.
To always access older milestones/version of your handbooks for reference/legal reasons.
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.
If you keep several Scroll Document managed handbooks in the same space as an internal knowledge base, use the Scroll Documents List macro to list all documents available in the space.
Manage versions of your handbook
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're 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.
If a version needs a review, the user needs at least view permissions within the version. For more information about restricting your content to the right users, see Manage Restrictions.
Keep track of changes and comments
In the authoring process, you most likely want to keep track of review comments and what has changed between two versions.
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.
For documents where time stamps are important, use the version description to note down when the version was approved and by whom.
Author Content for Specific Audiences
Are you a part of a large or international organization? 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 handbook or manual. These functionalities are delivered by the two extension apps:
If you’re a part of multilingual organization it may be necessary to translate parts of your employee handbook into different languages. With Translations for Scroll Documents you can manage translations of your documentation in Confluence in the native languages of your colleagues.
When the Working version has been reviewed and approved, you should save a new version of your document. We recommend you add the 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,
or integration with machine translation COMING SOON .
Conditionalize articles and text
If your organization has teams working in different countries, the topics in your employee handbook may vary depending on where your employees are based. For example, a standard topic like vacation and sick leave should be in every handbook, but the content may vary for a team in Australia versus a team in the UK.
With Variants for Scroll Documents you can deliver a variant of your handbook 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 handbook internally, you can choose between:
making one or multiple variants available in the Document reader,
or export a selected variant to PDF or Word.
Publish and Share Your Internal Documentation
When it’s time to release the newest version of your employee handbook, Scroll Documents offers the option to publish and share your documentation for your audience within Confluence. If you have an audience outside of Confluence, you also have the option to export the documentation into PDF or Word format using Scroll PDF or Word Exporter.
Publish within the author space
With Scroll Documents, you can author and publish content within the same space, while always keeping the Working version private.
To maintain a separate view for authors and readers, you can work with version restrictions, hiding the Working version from its future audience. The version/s you decide to make available, can be consumed by its audience in two ways:
Via the Document reader, where the readers also can switch between versions, languages, and variants if you have made more than one available.
Directly through the page tree in Confluence, where each public version and its pages will be available in their own section.
Keep in mind, that users cannot filter between variants when reading content directly through the page tree. In Confluence variants are best consumed via the Document reader.
Use the Share feature in Scroll Documents to create a link to the latest released version for your readers. The link will take the users to the Document reader with the shared version selected in the version picker. To learn more, see Share a Link to a Version.
Export to PDF or Word format
If you have an audience outside of Confluence, you can export versions of your employee handbook into an offline format. The exporting would then be achieved with Scroll PDF and Word Exporter, which you also can use for creating customized export templates. Each template can be styled to match your company’s brand identity.
In addition, if your organization consists of a diverse or international audience, you can also export translations and variants of your employee handbook.
Want to learn more?
Below, we have collected some resources with tips and tricks which could help you when managing a employee handbook: