Scroll Versions is a useful tool for managing pages in a Confluence space that are revised at arbitrary times, but are only “published” when the revisions, as a whole, are ready for public consumption. Examples of likely candidates for Scroll Versions are the InCommon Federation Library or the InCommon Trusted Access Platform Library, where there are multiple authors, but final, published, versions are vetted by a service manager, higher-level management, and/or an oversight group. Spaces that primarily support collaboration, such as those supporting working groups, are less likely have need of Scroll Versions.

This document provides some guidelines for the use of Scroll Versions in those cases where it is used. It is not intended to be a full introduction to document creation and management, only to likely ways that Scroll Versions may help that process for Trust and Identity.

Full documentation of Scroll Versions can be found at the vendor’s site: Scroll Versions.

The Document Revision Cycle

At a high level, a Scroll Versions enabled space will follow the following life-cycle:

  • Pages are created and/or revised from earlier versions.
  • Depending on the specific space, revisions and new pages may be reviewed for content, style, etc.
  • The final revision of all pages (for this cycle) is published.
  • The cycle is repeated.

With this in mind, the following decisions about people’s roles must be made for each space. These decisions may be formal or informal, as appropriate, and may change over the lifetime of the space.

  • Who are the authors who will be making the revisions?
  • What review will be required?
    • By the revisions’ authors?
    • By other authors?
    • By specifically-designated reviewers?
  • How will the decision to publish be made?

The following section outlines how these decisions affect role assignment within Scroll Versions.

Roles

Scroll Versions supports the following roles for people interacting with a Confluence space:

  • Author - A person who can create and revise the content. By default, this is a person with the Confluence add/edit permission.
  • Reviewer - A person who can read the content for the purpose of accepting (or rejecting) it.  A Reviewer cannot, however, revise the content. By default, this is a person with the Confluence view permission.
  • Doc-Admin - A person who can publish the content. By default, this is a person with the Confluence space admin permission.
  • Reader - A person who can read the published content. This is a person with the Confluence view permission.

The defaults apply when the specific Scroll Versions roles have not been assigned.  Within Trust and Identity, we will create them for new spaces, in case they’re needed in the future.

See Scroll Versions's Roles and Permissions for more information.

Location of Published Materials

Scroll Versions publishing either into the current space (where Authors, Reviewers, and Doc-Admins do their work), or into a different space. For our work in Trust and Identity, publishing into a separate space created specifically for publishing is probably most appropriate, but see Scroll Versions's Intro to Publishing for more information on the tradeoffs.  Also, when publishing, you will likely want to select all of the options of what to publish.

Identifying Versions

Space versions should be labeled in the form x.y, where x and y are integers representing major and minor releases, respectively. A new major release would represent a major restructuring of the information, whereas a minor release would represent incremental changes.

Scroll Versions understands the concept of successions of versions, where later versions inherit content from their preceding version; you declare the preceding version when you create a new version. Usually, a new version's predecessor would be the former most current version, but that's not required. This means, for example, that the published version of a space might be 1.3 while the space is undergoing a months-long restructuring for version 2.0. If, during the version 2.0 work, a correction must be applied to 1.3, version 1.4 can be created with 1.3 as its preceding version.  Version 1.4 can then be edited and published without affecting the work on 2.0. (You may need to apply 1.3's correction to 2.0, however, depending on the nature of the correction.)

A couple of notes:

  • Scroll Versions's versions and Confluence's revisions are not the same.  Scroll Versions’s versions refer to entire published (or yet to be published) spaces, whereas Confluence’s revisions refer to individual edits of individual pages. Confluence’s revisions are still maintained for each page, even when Scroll Versions has been enabled for their space. See Intro to Content Reuse for more information.
  • If you are converting an already-published, unversioned space to Scroll Versions, use version 1.0 for the initially-converted content. Then, create version 2.0 for the first modification under Scroll Versions.  This will preserve the state of the original, unversioned space.

See Scroll Versions's Versioning for more information.

Permalinks

Scroll Versions assigns "permalinks" to pages that allow multiple pages to have the same title, and do not change when the page's title changes. (See Duplicate Page Titles.) When you initially create a page, the permalink will default to the page title, which will likely contain characters that require special URL encoding, or conflict with pages you have created in the past (or will create in the future).  For that reason, make sure your permalinks:

  • are roughly based on the page's (original) title,
  • add qualifying words if the title might appear elsewhere in the space,
  • use only lowercase alphanumeric characters and dashes ("-") to replace spaces.

For example:

  • A page titled "How to Start Offering Services" would have a permalink of how-to-start-offering-services.
  • "How Do I Login?" would have how-do-i-login.
  • An "Introduction" page within a collection of pages about IdPs would have idp-introduction, whereas an "Introduction" page for SPs would have sp-introduction.

Note that you must check "Allow duplicate page titles in this space" in the Scroll Versions Settings to enable permalinks.

Relationship with Trust and Identity Document Stewardship

When a new version of a space is published, it should be considered for inclusion in Trust and Identity's document repository. See Trust and Identity Document Stewardship for more information.

Miscellaneous Tips

Include Libraries

Scroll Versions extends Confluences ability to share content, either within the same space, or from other spaces. See Scroll Versions's Intro to Content Reuse for more information.

Unversioned Pages

It is possible to exempt some pages from versioning. When this is done, changes to such pages will apply to all versions, even those that have already been published. This may be useful for legal notices, navigation bars, etc.  See Scroll Versions's Intro to Version Management for more information.

Variants

Scroll Versions can manage space variants, as well as versions. Variants are used to publish a space multiple times with slightly different content, each time there is a new version of the space. An example is the Atlassian documentation for their local server and hosted Confluence product offerings. This would not usually apply to Trust and Identity documentation, but may be useful in some circumstances. See Scroll Versions's Intro to Conditional Content and Variants for more information.

  • No labels