Skip to main content
Skip table of contents

Get Started

If you’re reading this article, it means that you have decided to take Scroll Documents for a spin, and we could not be more excited!

This is a practice tutorial, here you’ll learn how to:

  • create a document,

  • edit a version,

  • save a version,

  • compare a version,

  • and finally publish a version.

Before You Begin

Pre-requisites

To complete this tutorial you will need the following:

  • A Confluence 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

Important terms

Scroll Document

Simply put, a Scroll Document (a.k.a document) 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.

Documentation Page Tree

A documentation 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.

Documentation Root Page

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 part 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.

To get started, follow the steps below:

  1. Navigate to the space that you created in the pre-requisites step or any other space of your choice.

  2. In the space sidebar, click Scroll Documents from the Apps section to open the Document Library

  3. From the Document Library, click New document.

  4. Select Create from template.

Select New document option Create from template

5. In the Create from template dialog, make sure that the Product Documentation template is selected > click Next.

6. Leave the default values as is in the Document details form > click Save.

Well done!
You have now created your first document based on the Product Documentation template.

2. Save a New Version

After the document is created, you should 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.

Document manager with one Working version

A Scroll Document always starts out with a Working version. You 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.

To save your first version, follow the steps below:

  1. Click Save a version.

  2. In the New version dialog, update the values of the following fields:

    1. Version: “1.0”

    2. Description: “Baseline version”

  3. Click Save.

The new version appears in the version history table along with the Working version. The versions are automatically sorted according to the version name.

Great!
You have now saved your first version.

3. Edit the Working Version

Now that you 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:

3a. Add a new page to the working version

To add a new page to your Working version of your document, follow these steps:

1. From More page tree actions (•••) in the Working version select Organize Page Tree.

Document manager with more page treen actions selected

2. In the Organize Page Tree dialog, click on the plus (plus) to add a new blank page, let’s name it “Best Practices” and press enter on your keyboard.

3. Click Save to finish adding the page.

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.

3b. Add content to the new 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.

To add content to your new page, follow these steps:

  1. Click the Working version link in the version history table. This will redirect you to the root page of your documentation.

  2. From the page tree on the left, open the new page titled - “Best Practices”, that you had added earlier.

  3. Click Edit in the top right of the page to edit the content on the page in the Confluence editor.

  4. In the editor, feel free to add any content to the page and when ready, click Publish.

Great job!
You have successfully added a new page to your documentation.

4. Compare Versions

Now, before publishing a version, you may want to make sure that there were no unwanted changes 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.

To compare two versions, follow these steps:

  1. Click Document Toolbox, on the top-right of the page.
    (info) Info: 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.

  2. Click Manage (the cog icon) in the Document Toolbox in order to navigate back to the Document Manager.

  3. Click Compare versions located next to Save a version, this opens the comparison tool.

  4. Scroll through the content, or use the Previous/Next buttons at the bottom to navigate through the changes between the two versions.

  5. When ready, click X to close the dialog.

  6. (Optional) Click Save a version to save a new version.

Nice!
Now you know how to compare versions before a release.

5. Publish a Version

Now that you're familiar with editing, comparing, and saving versions, let's explore how to share your work with others. Scroll Documents lets you publish a specific version of your document within Confluence itself. You have two options for publishing:

  • Publish your content to a separate space.

  • Publish your content to a specific page within your existing authoring space.

Below, we’ll show how to publish to a dedicated target space. To publish a version, follow the steps below:

  1. First, you have to create a dedicated target space.

Ensure you have Add page permissions in both spaces.

  1. Go to the Document Manager of your document.

  2. Click on Publish.

  3. Choose Publish to Confluence.

    Publish to Confluence option via Document Manager
  4. Select the version to publish, and click Next.

  5. Search for and select the target location.

    Dialog to search for target space

  6. Choose the parent page in the target space where the content will be added.

  7. (Optional) If needed, add a prefix to avoid page title conflicts.

If there are no conflicting page titles, and you choose not to add a custom prefix, existing version prefixes will be removed from the published page titles.

  1. (Optional) Select if you want to publish page labels.

  2. Click on Publish.

Great!
You have successfully published your first version.

Troubleshooting

Encountered an issue? No problem! Check out our comprehensive Troubleshooting section for common issues and their resolutions. If your issue is not listed there, do not hesitate to reach out to our dedicated support team.

What’s Next?

Now that you are familiar with the basics of Scroll Documents, you can try out some of the more advanced features:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.