This use case describes how you can author and maintain versioned product documentation in Confluence and deliver it to your customers as a public documentation site using Scroll Documents. Documentation could also mean manuals, user guides, knowledge base articles, etc. depending on how you refer to them in your organization.
The basic workflow enables you to:
- Author documentation as documents in your team's Confluence instance
- Save a version of your documentation when it's ready for release
- Publish the newly saved version of the documentation by copying the document to a public space, making it available to your users or customers
This approach also makes it possible to proactively work on the next version of your documentation as the product is in development, and publish the documentation when the release is ready.
Prepare a public Confluence space
Create or designate a public Confluence space for your users to access the documentation. In this guide, we'll refer to this as the public space.
This public space can be viewed by anonymous users, meaning anyone inside or outside of your organization.
Prepare your documentation space
In your private Confluence instance, create or designate a space for authoring your documentation. In this guide, we'll refer to this as the documentation space.
Since Scroll Documents defines a document as a Confluence page and all of its children, we recommend structuring all of the pages contained in your documentation as a single page tree.
This also works if you are managing documentation or user guides for multiple products in the same Confluence space. See the page tree structure on the left of some multiple example products:
With this structure, you will be able to save versions of the page tree, enabling you to take a snapshot of the content across multiple pages at once. You'll also be able to publish the entire page tree with just a few clicks.
With your documentation structure in place, define the page tree as a document. To do this, open the Document toolbox on the parent page of the documentation and click Convert to document:
Depending on your documentation structure and what you would like to display in your public space, you may want to create multiple documents.
Manage documentation as a document
By defining your documentation as a document, you're able to manage multiple Confluence pages as one unit in the documentation space. Your team enjoys the same benefits of authoring content in Confluence alongside a few extra features like export options and status labels to indicate the progress of the documentation.
Create a new version
When you're ready to release your documentation, simply save a new version. This will create a snapshot of the content across all of your pages at this point in time:
This new version will appear in your version history. You can reference all versions at any point from this version history in order to track how your product evolves over multiple releases.
From the actions menu on the Current document, click Copy.
In the Copy dialogue:
- Remove the 'Copy of' prefix from the Title
- Set the Space to your public Confluence space
- Select the Parent page as the public space's Space Home Page
- Click Copy
You'll want to double check restrictions on the document in the public space to ensure it's available to your audience.
Note: If this document already exists in the public space or you are publishing a new version, you can replace the existing document in the public space with the copy and replace feature.
A message will appear explaining that you will need to decide what to do with both copies – keep both documents in the target space or replace the existing document in the target space. If you are using the copy feature to replace an existing version with a new one, we recommend replacing the document.
Now the documentation is available to the public. When your readers open the documentation in the Reader, they will be able to read through the entire documentation in one view with an interactive outline on the left rather than clicking through multiple Confluence pages to find answers to their questions:
Start working on the next version of your documentation
With the new version published to the public space, you can immediately start working on the next iteration of the documentation to keep pace with development.
Update content, add new pages or sections to the document, and follow the steps above to publish the next version of the documentation when you're ready to release.
As your product evolves, you can utilize the Scroll Documents' compare documents functionality to see what has been added, changed, or removed from one version to another.
Authors or reviewers can also compare the last published version in the public space with the new version to see all changes in one view. This cuts the documentation review process down to just a few minutes and allows you to catch mistakes and make updates before your documentation goes live.
Export documentation to PDF or Word
Scroll Documents integrates with Scroll PDF and Word Exporter, enabling you to create styled PDF or Word exports of your documentation.
See a public example library