Cops, crims and Confluence 4.0 change management

Atlassian has just released Confluence 4.0, a major update to the wiki software. The highlight of this release is a smart new all-in-one editor. It replaces the two editors available in earlier versions of the wiki. Now, as you would guess, the editor is the heart of the wiki. When the editor changes, the world changes. πŸ˜‰ That’s true if you spend all of your day on the wiki, as I do. How can we make sure it’s not a world-shattering change for people when they get the new Confluence? Technical writers and change management to the rescue!

Imagine this: You walk into the office on Monday morning, twitching your eyebrows in a vain attempt to get your eyes wide enough open to see the computer screen. The calendar pops up. Yikes, there’s that meeting in 10 minutes and the wiki page is not quite ready yet. Gulp a mouthful of strong hot Java. Fire up the trusty wiki. Click the edit button. What the…!??!! Someone’s changed the wiki. No more wiki markup editor. No more rich text editor. Your brain breaks up into little chunks and skitters away across the universe. Its last cohesive thought is, Why was there no warning of this change?

Luckily, the above paragraph is fiction. πŸ™‚Β  The Confluence technical writers have spent quite a bit of time on some change management material, aimed at helping people prepare for the new editor. This post is about technical communication and change management. It’s also a bit about Confluence 4.0. πŸ˜‰

The Confluence 4.0 change management guide

The front page of the change management guide is here: Planning for Confluence 4.0. It summarises the change management guides available for each type of audience: administrators, developers, and other wiki users.

The guides cover a number of aspects of Confluence 4. To help people get up and running fast with the new editor in particular, we have created some quick reference guides:

We published the Confluence 4.0 Editor FAQ quite some time back, to give people a place to ask questions and a page to watch for news and updates. It’s been very interesting to see the feedback from everyone. The product managers, developers and QA engineers have been kept quite busy responding to questions and suggestions, as you can see from the comments on that page.

A quick note to wiki markup fans

Take heart. Wiki markup never dies!

Aims of the change management guides

The guides are designed for business users, and primarily for managers and team leaders who will need to train their staff and update their in-house procedural documentation.

When an organisation decides to upgrade its Confluence site to Confluence 4.0, the change management team can make use of our guides to let the wiki users know what’s about to happen. They can prepare training material and quick reference guides based on the material we’ve created.

A story of cops and crims

Where did the idea for the change management guides come from? Back in May 2010, I wrote a blog post on our internal wiki suggesting the need for this sort of documentation at major software releases such as Confluence 4 looked like becoming. As an illustration, I told this story:

A while ago I worked as technical writer for the New South Wales Police, during the time when the NSW Local Court Reform Act was passed. The new Act affected the way policemen arrested people, processed the arrest in the police stations, took fingerprints, entered information onto the police computer system (called “COPS” of course), held the suspect in the holding cells, took them to court and handled bail. In fact, it changed just about everything related to arrests and court procedures.

My role was pretty interesting. I had to document the changes to COPS (a green-screen mainframe system!) as well as do the change management for the local bobby on the beat. I designed posters that were to be stuck up on the walls of police stations around the state, quick-reference cards for court officers, and in-depth procedures for the guys who processed the arrest and holding of the suspect. I wandered around the depths of the Kings Cross police station (an education in itself) and watched people reporting for bail.

It was a revelation to see how the change affected people who were just trying to do their day job and now had to deal with a totally changed computer system too.

That blog post was over a year ago. Since that time, we’ve been planning and working on the Confluence 4.0 change management guides.

A new editor? Could do it with me eyes closed, mate!

Cops, crims and Confluence 4 change management

I can haz read teh docs. No wurriz, she'll beh right.

I snapped this photograph at the Sydney Wildlife World last week. It’s a real koala, not a toy. Promise! Its less than elegant scientific name is Phascolarctos cinereus.

I’m excited about this new direction in the documentation. I hope many organisations and many people will find the change management guides useful! I also wonder how many other technical writers focus on change management as well as straight “how to” guides. Let me know if you’ve been doing something similar.

A bit of marketing fun

The marketing team have also been busy. Last week they published a neat, cheeky infographic placing the wiki in the world’s communication timeline: Communication through the ages. There is also a web page, published today, with an excellent overview of the new features in Confluence 4.0.


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 20 September 2011, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , , . Bookmark the permalink. 8 Comments.

  1. Nice post as always. I enjoy your simple, no fuss writing style!
    In the Agile world, it is critical to help users understand what changed from the previous release, especially since releases are so close to each other. A change management plan is a good idea. I like the fact that you had FAQs prior to the release to help people get their heads around what’s coming! We produce something called a Change Summary for one of our complex products. This doc is a favorite with the guys in the field. It gives them a quick snapshot of what changed, and if need be, they can go back and read the regular user guides for details.

    • Hallo Anu
      Great comment, thanks! I like the idea of your change summary too. We publish release notes for each release, which may be similar to the change summary. The release notes tend to be a bit of a marketing tool, as well as saying what has changed. It sounds as if the change summary may be more down to earth, valuable indeed to engineers and people out in the field.
      Cheers, Sarah

  2. Hello, Sarah!
    Very inspiring post, as usual.
    And congratulations on the best Confluence release I can remember πŸ™‚
    Your team is something – I’m really enjoying reading and watching your release notes, blog posts, even marketing posters!

    _Thank you_

  3. Sarah,

    This is another great post! We’re in the process of planning for a significant navigational/UI change in our enterprise product and as the sole technical writer, I’m wrestling with exactly the issues addressed here. I especially like the idea of creating a place where we can post Q&A and respond to user questions/concerns ahead of time.

    One thing I’m wondering – did you do any in-app guidance (mouseover/popup/”more info”/etc) after you made the changes? We’re trying to figure out how to help our users be successful, once we’ve implemented the changes, and have yet to really come up with a clean, efficient way to lead them toward success.

    Thanks so much for your posts. I regularly check them because I find them so useful!

    • Hallo Paul

      Good question! Confluence does display a “what’s new” dialog that gives people an overview of the changes in a new release. The dialog pops up when someone logs in for the first time after the site has been upgraded. After reading the content, the viewer can banish the dialog for ever. The content includes a list of new features and changes, and some instructional videos and links.

      Google does this kind of thing really nicely, and it’s probably closer to what you mean. If you use Gmail or Google Docs, you’ve probably seen the little bubbles that pop up, pointing to a UI element, mentioning the change and offering a link for more info. Very neat.

      Thanks for a great comment!
      Cheers, Sarah

      • Hi Sarah,
        thanks for the reply. We’re contemplating the “what’s new” popup and seem to have a 50/50 split in terms of like/hate it. (Other web apps we use inhouse do this and some folks love it and some folks… you know how it goes.)

        We’ve also seen the Google Docs approach, and that seems to work pretty well, as long as you have both old and new UI at the same time. It’s a bit more problematic when you can’t pop up a hint based on what a user is trying to do. By that I mean that if they are searching in the old area and you want to encourage them to use the feature from the new spot, you can do a “you know, the settings are being moved over… here” but if the old location is no longer accessible, there’s no way to know what it is the user is trying to do. (not sure if that makes sense, but I’ll leave it. :> )

        Also in our mix is the sort of video clip approach that a lot of mobile apps are taking now. When you first hit a changed screen, do a popover clip showing how things have changed.

        I think I’m going to push hard for the pre-change communication that Atlassian took with the changes you describe. Not everyone will see it before hand, but it’ll be there even after the changes, as a reference for late-comers.

        Thanks again for the great post(s).


      • Hallo Paul

        That’s a very comprehensive approach. I agree that the change management guides, for use before the release and upgrade, are very valuable. In some cases they are essential. As you say, not everyone will read them, but most people will. Especially customers in large organisations where many staff members will be affected by the change. Confluence 4.0 is a big change from 3.5, and I think the impact on customers would have been very unfavourable without the guides we wrote.

        One hint is to link from the release notes to the change management guides, so that people know they exist. You can even cast them as a feature of the release. πŸ™‚

        Another idea is to put up a sandbox site running the latest version of the app, even while still in beta. People can play around in it. The site would of course include the popups and videos etc.

        Cheers, Sarah

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: