If you are reading this article, it means that you have decided to take Scroll Documents for a spin, and we could not be more excited!
In this tutorial, you will learn how to create a new Scroll document and save a version. From there, we will show you how to edit, compare and share your document.
Before you begin
To complete this tutorial you will need the following:
A Confluence Cloud instance with Scroll Documents installed. Learn how to install Scroll Documents.
A new or existing Confluence space. We highly recommend creating a new space for this tutorial.
The following space permissions -
All - View
Pages - Add
Attachments - Add
Simply put, a Scroll document (a.k.adocument
) lives in a Confluence space, and is a container for your documentation page tree and all its versions.
A Scroll document always starts out with a working version and is represented in the form of a card in the Document Library.
Adocumentation page tree
on the other hand refers to the scope of pages within a Confluence space that represent a set of related content that you want to version and manage together.
The Documentation page tree can either be -
a single page, or
a sub-set of the space page tree, or
the entire space page tree
When you create a new Scroll document the documentation page tree is added as the working version of the document.
In Scroll Documents, the top-level page of your documentation is known as the root page. This may vary depending on the scope of your documentation in Confluence. E.g.
If your documentation consists of only a single page, then this page is considered as the root page.
If your documentation is organized in a page tree within a space, then the top-level page of the tree is considered as the root page.
If an entire space represents your documentation, then the space home page is considered as the root page.
In case you add any pages below the document root page in the future, Scroll Documents will consider them a part of the documentation, and will be subject to versioning.
1. Create a new document
In this tutorial, we will create a new document using a pre-defined Product Documentation template, that ships out-of-the-box with Scroll Documents. This template is a great example of how you can organize your documentation, and helps you get started with the app quickly.
Start by navigating to the space that you created in the pre-requisites step or any other space of your choice.
In the space sidebar, click Scroll Documents from the Apps section to open the Document Library.
From the Document Library, click New document.
Select Start from template.
In the first step of the wizard, make sure that the Product Documentation template is selected, and then click Next.
In the next step, leave the default values as is in the Document details form, and click Save.
2. Save a new version
After the document is created, you land in the Document Manager. The Document Manager is where you manage your documentation and all its versions. It is like the ‘command center’ for your document within your space.
A scroll document always starts out with a working version. We will learn more about the working version in the next section. For now, let’s start by saving the initial state of your documentation.
We highly recommend saving the initial state for all your documents. Saving a version when you start out with a document is a good way to create a baseline for your content. It enables you to compare future versions of your content to the initial state.
Click Save a version.
In the New version dialog, update the values of the following fields:
Description: “Baseline version”
The new version appears in the version history table along with the Working version. The versions are automatically sorted according to the version name.
3. Edit the working version
Now that you have have saved a baseline version, you are ready to update the working version of your documentation.
Think of your working version as the continuously progressing version of your document. Use this version to prepare changes to your document and save a version once complete.
In this section, you’ll learn how to:
Add a new page to the working version of your document.
Add content to the page using the Confluence editor.
Add a new page
From the ••• menu of working version select Organize Page Tree.
In the Organize Page Tree dialog, click to add a new blank page, name it “Best Practices” and press enter.
Then, click Save to finish adding the page and return to the Document Manager.
If you look at your space sidebar on the left, you can see how the new page has been added to your documentation page tree.
Add content to the page
Now that you have added a new page to your documentation, it’s time to add some content to it. You will add content to the pages of your documentation using the Confluence editor.
Click the Working version link in the version history table. This will navigate you to the root page of your documentation.
From the page tree on the left, open the new page titled - “Best Practices”, that you had added earlier.
Click Edit in the top right of the page to edit the content on the page in the Confluence editor.
In the editor, feel free to add any content to the page and when ready, click Publish.
4. Compare versions
Congratulations! you have successfully added a new page to your documentation. Now, before publishing a version, we want to make sure that there were no “unwanted updates” that have sneaked into your documentation.
You can do this by comparing the working version of the documentation to the “baseline version” that you had saved earlier.
Click Document Toolbox, on the top-right of the page. Think of the Document Toolbox as a ‘quick actions menu’ for your scroll document. It contains, among other features, shortcuts to the most important actions you will need when authoring your documentation. But for now, let’s use it to quickly navigate back to the Document Manager.
Click the cog icon in the Document Toolbox in order to navigate back to the Document Manager.
Once in the Document Manager, click Compare versions located next to the Save a version action. This opens the Comparison Tool.
Scroll through the content, or use the Previous/Next buttons at the bottom to navigate through the changes between the two versions.
When ready, close the dialog by clicking the 'X' button on the top-right and optionally save a new version.
5. Read and share your document
The Document Reader is a dedicated view of your document and all its versions. The Document Reader is an ideal way to share your document with your readers in Confluence.
A Document Reader will always display the latest approved version of your documentation by default. Learn how to Set and Track Workflow Statuses of your saved versions.
In the Document Manager, click the Book Icon on the top-right. The Document Reader dialog displays.
You can now read the content, share, and export any version of your document.
6. Browse all documents in a space
So far, we have created one scroll document, but you don’t have to stop there. You can create as many scroll documents within your Confluence space as you want.
The Document Library is the home for all documents created within your space. It enables you to access, organize, classify, and filter documents from one place.
In order to navigate to the Document Library, click Go to library link on the top of the Document Manager.
Alternatively, you can always click Scroll Documents in the space sidebar in order to navigate to the Document Library.
You have successfully completed the Getting started tutorial for Scroll Documents. You have created your first document, saved some versions and compared the versions using the comparison tool.
Now that you are familiar with the basics of Scroll Documents, you can try out some of the more advanced features -