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!

Recording of webinar about Confluence wiki as documentation platform

On Thursday I was a co-presenter in a webinar about Confluence wiki as a platform for technical documentation. The recording of the webinar is now available, as well as my slides, and a wiki page for discussion and questions.

The recording

The video is available on YouTube:

The slides with speaker’s notes

The slides for my part of the webinar are available on SlideShare: Confluence as a platform for technical documentation.

To see the speaker’s notes, click the tab labelled “Notes on slide n” under each slide (next to the comments tab).

Wiki page for discussion and questions

The recording, slides and other information are also on a page on the Atlassian documentation wiki: Confluence as a Platform for Technical Documentation Webinar. Drop in there to see what people are saying.

Congratulations to the prize winners!

Twelve lucky attendees won prizes in a draw after the webinar. Congratulations all! The names of the winners are announced in an Atlassian blog post.

Webinar includes sneak previews of new wiki tech comm products

For an overview of the three sessions in the webinar, take a look at my earlier post: Invitation to join me in webinar about Confluence and technical documentation.

Just to entice you, here are a couple of hints about what my co-presenters talked about and demonstrated during the webinar. :)

Tobias Anstett from K15t Software talked about his company’s vision that wiki technology is the future of technical documentation. He gave two demos of the Scroll DocBook Exporter and the Scroll EPUB Exporter, which you can use to convert Confluence content to DocBook XML and EPUB formats. Tobias also hinted tantalisingly that K15t Software will announce two new products at Atlassian Summit in May. The two products focus on the planning, creation and quality assurance parts of the documentation life cycle. There’s also a solution in the works for wiki-based online help, including the ability to add user comments. Exciting!

Darryl Duke from Stepstone Technologies demonstrated the Zen Foundation theme. I loved his point that collaboration is and always will be about human interaction. So, to get people to use a wiki, familiarity and visual integration are very important. People need to feel that they belong on the wiki. The wiki must be a high quality reflection of the community and brand that it serves. With the Zen theme, you can produce a very sophisticated look for your wiki site. Zen also customises the wiki editor. Darryl gave a very cool demo of how you can drag and drop sections of a page, edit a section as an independent block of content, and use master pages to define standard page layouts. He then gave us a sneak peek of a new interactive brand designer that Stepstone Technologies will launch at Atlassian Summit in May. (In the Zen theme, the brand is the collection of CSS and images that determine the look and feel of your site.) Very smooth indeed!

What’s it like presenting a session in a webinar?

At the beginning of this post, I wrote that the webinar took place on Thursday. Actually, it was 1 a.m. on Friday morning here in Sydney! It felt a bit odd, sitting all alone and  speaking into the ether at 1 a.m, hoping that people were listening. It was great when I saw all the questions flooding in, and knew that people really were there. The webinar hosts later told me that more than 200 people attended. That’s so cool.

One tip I’d give to people who are planning to take part in a webinar: Practise beforehand. You’ll need to play with the webinar software, and to run through your presentation. The software is fairly easy to work with, so one practice session is enough to get to grips with that.

Running through your presentation is even more crucial. I’d recommend doing the run through at least twice. Also, do it in the same place and if possible at the same time as the real event. Speak your presentation out loud. You’ll feel like a banana (in other words, a bit silly) but it’s better to feel that way when you’re practising than during the actual event. Why should your practice session be at the same time as the actual event? It helps you to identify any possible hazards, such as loud noises or the need for an extra light. In my case, I decided to hold my practice session during the day time instead of at 1 a.m. As a result, I didn’t realise how dark it would be in the room where I was huddled at the bottom of the house, trying not to wake everyone else. So I had to rush around looking for an extra light just before the webinar started!

Doing the webinar was interesting and fun. Thanks so much to everyone for attending, and to Terrence and Matt at Atlassian for holding everything together behind the scenes. And congratulations to Tobias and Darryl on their excellent presentations. Co-presenting is the way to go!

Writing a book with DocBook and a Confluence wiki

We’re in the final stages before sending my book off to the printers. Exciting! While we wait, let me tell you a bit about how the publishing team and I have produced the book. We’re using a Confluence wiki and DocBook XML.

Cover of "Confluence, Tech Comm, Chocolate"Here’s our process in brief:

  • Plan, write and review the book on a Confluence site.
  • Use the Scroll Wiki DocBook Exporter to convert the content to DocBook XML.
  • Use DocBook XSL-FO style sheets to create a PDF file for sending to the printers.
  • Use XSL to generate ebook formats too.

This post is about writing and reviewing the book on the wiki, and converting the Confluence content to DocBook XML – the first two points in the list above. Richard Hamilton, at XML Press, is the expert on the further DocBook processing.

A bit about the book

The book is called Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Details are at XML Press. It is all about developing technical documentation on a wiki, with a focus on Confluence wiki. And just to be ultra meta, I’ve written the book on a Confluence site. Dogfooding FTW!

Writing, planning and technical review on the wiki

Richard Hamilton and I have spent the last nine months on a Confluence wiki site. We kicked off our planning there in May 2011. Since then, I’ve spent around 400 hours writing the content on the wiki. Ryan Maddox, our illustrator, has uploaded his images onto the wiki. For two weeks in early December, the technical reviewers joined us there too – six knowledgeable and enthusiastic people:

The wiki was abuzz with review comments, opinions and counter-opinions, laughter and chat.

Now it’s gone a bit quiet while Richard and I work on the last stages of book production. When we launch the book, we’ll open up the wiki site too. You’ll be able to join us there and make it buzz again. :)

DocBook for the publication processes

DocBook is an XML standard for documents, developed by O’Reilly as a means of making their publishing process more efficient. It is now an open standard maintained by OASIS.  Richard Hamilton, at XML Press, uses DocBook XML to publish a range of books on the subject of technical communication. Using a customised set of the open source XSL style sheets for DocBook,  Richard can create HTML, PDF (through XSL-FO), EPUB and other epublishing formats from the DocBook source.

Converting content from Confluence wiki to DocBook XML

So, I’ve finished writing the book and the reviewers have worked their magic too. It’s all on a Confluence wiki. The content is stored in the Confluence database in wiki format. How do we get it to DocBook so that Richard can create the print and ebook formats?

Enter the Scroll Wiki DocBook Exporter.

Scroll Wiki DocBook Exporter is a plugin for Confluence, developed by K15t Software. (A plugin is a small piece of software that extends the functionality of the wiki. It is similar to an add-on for a web browser.) Once you have installed the Scroll Wiki DocBook Exporter on your Confluence site, you can export a page, a set of pages or an entire space, to DocBook XML.

How to use the Scroll Wiki DocBook Exporter

The first thing is to add the plugin to your Confluence site. You need to be a Confluence system administrator, then you can install the plugin in the usual way:

  1. Log in as a Confluence system administrator.
  2. Choose “Browse” > “Confluence Admin” > “Plugins” > “Install”.
  3. Type “scroll wiki docbook exporter” into the search box and click “Search”.
  4. Click the name of the plugin in the list of search results, to open the panel showing the plugin details.
  5. Click “Install Now”.

See the Confluence documentation on installing plugins.

You will need a license key from K15t Software. They provide a free evaluation license that gives you full functionality for 30 days.

Once the plugin is installed, a new option appears in the Confluence “Tools” menu, allowing you to export the content to DocBook format.

  1. Go to the page that you want to export. If you want to export a set of pages, go to the parent page of the set.
  2. Click “Tools” > “Export to DocBook”.
  3. Adjust the options in the dialog that pops up:
DocBook Exporter dialog

Scroll Wiki DocBook Exporter

When you are ready, click “Start Export”. The plugin will create a zipped file containing the DocBook XML and attachments, and will offer the file to you for downloading.

A sample of the output

Here is one of the book’s pages on the wiki:

Book's front page on the wiki

Front page of the book on the wiki

And here is an extract of the DocBook XML:

<?xml version=”1.0″ encoding=”UTF-8″?>
<book xmlns=”http://docbook.org/ns/docbook&#8221; xmlns:xlink=”http://www.w3.org/1999/xlink&#8221; xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance&#8221; xsi:schemaLocation=”http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd&#8221; version=”5.0″ xml:id=”scroll-bookmark-1″>
<info>
<title>Confluence, Tech Comm, Chocolate</title>
</info>
<part xml:id=”scroll-bookmark-2″>
<title>Confluence, Tech Comm, Chocolate</title>
<chapter xml:id=”scroll-bookmark-3″>
<title>A wiki as platform extraordinaire for technical communication</title>
<para>By Sarah Maddox</para>
</chapter>
</part>

[SNIP]

<index />
</book>

Index, footnotes and figure captions

The Scroll Wiki DocBook Exporter supports these too. The plugin adds a number of macros to Confluence, which you can use to mark up the index entries, footnotes and figure captions. I’ll write another post with the details. I’m sure many people are agog to know how this works. ;)

Working with K15t Software and XML Press

Richard and I have worked on this project with Tobias Anstett and the rest of the team K15t Software.  They are great people to work with: knowledgeable, enthusiastic and energetic. As far as I know, this is the first time anyone has written a book on Confluence for publication via DocBook XML. We have added new functionality to the plugin, especially for the index and footnotes, adapting and tuning as we go.

Thank you all. It’s exciting to help perfect a plugin that many other authors and technical writers will be able to use.

And I can’t wait to get my hands on a copy of the book!

Follow

Get every new post delivered to your Inbox.

Join 1,488 other followers

%d bloggers like this: