Blog Archives

Version management gets serious with Confluence Scroll Versions plugin

The team at K15t Software have just announced the first production release of Scroll Versions, an exciting new plugin for Confluence wiki. Our technical writing team has been working with the K15t guys on specifying and testing Scroll Versions. We and K15t are delighted with the 1.0 release. What’s more, K15t have exciting plans for adding even more features to the plugin. These features are what technical writers dream of. ;)

This video, produced by K15t Software and narrated by Kelly McDaniel, gives an excellent overview of the plugin’s functionality.

Why I’m excited about Scroll Versions

For me, the selling point is version management. And I’m over the moon about the enhanced features planned for future release.

What’s new about the version management offered by Scroll Versions? The standard Confluence functionality (without any additional plugins) includes a good solution for version management of single pages, and of entire manuals:

  • At the page level: Every time someone updates a page, Confluence saves a new version of that page. You can see the page history, compare two versions to see what changed, and revert to a given version at any time.
  • For version management of a manual or a set of documents, we use spaces. For each major release of the product, we copy the contents of a documentation space to a new space and brand it for the new version of the software.

But it’s difficult to mark a set of documents for publishing in a batch. For example, you may want to publish a page of release notes and a couple of minor updates for a point release of the product. Or you may be developing a new subset of documentation, not related to a product release, and you want to publish all the pages at once. Or, of course, you’re working towards a major software release and need to bundle a batch of new pages, updates and deletions for publication on release date.

In an agile environment, you may need to have a number of versions – let’s call them “branches” – running at the same time, each for a different feature. And you need to publish those versions – or “merge those branches” – at fairly arbitrary time intervals.

This is what Scroll Versions can give us now. You can have a number of versions of your documentation in draft state. You can create and manage multiple versions of the documentation, all in one Confluence space, all at the same time. A version consists of a set of new and updated pages, and even page deletions.

When you’re ready, you can publish a given version of the documentation. The effect is that people who view the content of the space will see that version only.

The other versions, both past and future, remain available in the space. You can publish any version at any time. You can even go back to a previous version. You can publish your version to the current space or to a new space. The versions are incremental. For example, version 1.2 of your documentation will include all the updates from version 1.1. You can change these dependencies at any time, making version 1.2 dependent on version 1.1.9 instead of 1.1, for example.

A future release of Scroll Versions will add conditional publishing, as well as the ability to publish from one space to a different, already existing space, thus merging the new version with existing content in a different space.

This screenshot shows the Scroll Versions configured in my test documentation space. I have set up a few versions:

  • 1.0 – the original version of the documentation that existed when I installed Scroll Versions.
  • 1.0.1 – a bug-fix release, based on version 1.0. This is the currently-published version of the documentation. I used Scroll Versions to publish it.
  • 1.0.2 – an upcoming bug-fix release, based on version 1.0.1. This version is not yet published.
  • 1.1 – the next major release, based on version 1.0. See the nifty branching visualisation to the left of the version numbers!

I would probably change the dependent version of my 1.1 release a few days before publishing it. I would make it depend on the last bug-fix release, which may at that stage be 1.0.9, for example. By changing the dependency, I make sure that version 1.1 picks up all the changes made in versions 1.0 to 1.0.9.

Other goodies in this release

Using Scroll Versions, you can have more than one page with the same name in the same space. Yes, duplicate page names are now possible.

There’s also a new macro for enhanced content reuse. And you can add permanent identifiers to pages, which stay the same across multiple versions and different spaces – useful when you want to use the wiki  as an online help solution.

How to set up and use Scroll Versions

I’m using Confluence 4.2 and Scroll Versions 1.0.1.

Note: For the purposes of this post, the words “add-on” and “plugin” mean the same thing. The Atlassian Marketplace refers to “add-ons” and the Confluence user interface calls them “plugins”. The term “add-on” is broader than “plugin”, since an add-on can refer to other types of extensions. Scroll Versions is a plugin.

If you don’t already have Confluence, you can install an evaluation Confluence site and use it for 30 days free of charge. It’s quite easy to install Confluence on a laptop or desktop computer:

  1. Go to the Confluence download page.
  2. Download the installer for your operating system.
  3. Run the installer and follow the instructions it gives you.
    • Choose the default options for an evaluation installation.
    • When the installer has finished, it will open the Confluence setup wizard in your web browser. Follow the instructions to configure Confluence, again choosing the default options for an evaluation installation.
    • Choose to include the sample data. This will give you a wiki space full of content that you can play around with. It’s called the “Demonstration” space and has a space key of “ds”.
    • Generate an evaluation licence key as prompted, and paste it into the Confluence licence key text box.

To set up Scroll Versions on your Confluence site:

  1. Go to the Scroll Versions plugin page on the Atlassian Marketplace.
  2. Choose the big blue button that says “Free 30 Day Trial”.
  3. Follow the instructions as prompted, to do the following:
    • Generate a 30-day license for Scroll Versions.
    • Download the plugin (a JAR file).
    • Install the plugin via the Confluence administration screen.
    • Add your Scroll Versions licence key via the Confluence administration screen.

Now you have Scroll Versions on your site. The next step is to enable it in your documentation space:

  1. Go to a page in the space. If you’re using an evaluation site, you can use the Demonstration space at this URL: http://localhost:8090/display/ds
  2. Choose “Browse” > “Scroll Versions”.
  3. Follow the instructions as prompted, to do the following:
    • Activate version management in your space, and choose the version for the content currently in the space.
    • Define the groups of people who will be able to write version-controlled content (the “Authors”) and the people who will be able to configure the Scroll Versions behaviour in the space (the “Doc-Admins”). Hint: If you’re evaluating the plugin on a test site, it’s easiest just to assign the “confluence-users” group to both these roles. The “confluence-users” group consists of everyone who has permission to log in to your Confluence site.
    • Determine whether your space should allow duplicate page names.
    • Save your changes.

Your space is now configured to use Scroll Versions for version management. The next thing is to add a version or two, and start playing with them.

To add a new version of your documentation in your space:

  1. Go to a page in the space.
  2. Choose “Browse” > “Scroll Versions”. You will see that there are now two big green buttons, one called “Manage Versions” and one called “View Configuration”. The second button takes you back to the configuration steps that you’ve just done above. If you clicked it, come back again!
  3. Choose “Manage Versions”.
  4. Choose “Add Version”.
  5. Add the details for your new version. For example, it may be version 1.0.1, which is based on version 1.0.
  6. Add a couple more versions, just for something to play with.

When you go back to the pages in your space, you’ll see the Scroll Versions information panels at the top of each page. The version information panels and options are visible only to the people in the groups you specified as Scroll authors or doc-admins. Other viewers of the space will see just the wiki page, as usual.

Now that you have Scroll Versions set up, it’s a good time to watch that video again (at the top of this post) and then start playing with the product.

More reading, and feedback

This is K15t Software’s blog post announcing the release:  Announcing Scroll Versions – Concurrent Version Management for Atlassian Confluence.

The documentation is here: Scroll Versions Documentation.

The team at K15t Software are very keen to have our feedback. Happy wiki version management!

Follow

Get every new post delivered to your Inbox.

Join 1,465 other followers

%d bloggers like this: