Some Notes on Moving Content to Confluence

Confluence is a super-charged wiki from Atlassian, the same company that makes the popular issue tracker, JIRA.  As you'd expect with a normal wiki, its most popular function is as a knowledge base, documentation hub and FAQ location, but due to it's tight links to JIRA (and other Atlassian products) it's also used for showing sprint reports, burn downs, burn ups, work in progress, and lots of other reports using data taken straight from JIRA.

In this post we're going to focus on the traditional wiki usage: documentation and knowledge management, and specifically some do's and don'ts when moving existing documentation and knowledge assets into Confluence.  Some of the points below are specific to Confluence, some are best practise whenever you're moving knowledge from one place to another, but they're all born of experience and hopefully they'll help you avoid some of the pitfalls.

The most important points first:

• If you're a technical person, get a content person in before you move anything.  They'll spot issues you won't. 
• If you're a content person, get a technical person in before you move anything.  They'll spot issues you won't.
  

I'm more of a content person, and having some technical people (i.e. developers) around helps immensely.  A developer's first thought is always "How can I do this through code?", which means they're much better at spotting situations where a batch file or a regex or some CSS will make everything a lot quicker and less manual.  When I was looking at moving documentation from some internal wikis, it was developers who helped me find the appropriate export functionality and worked out whether I could take that format and import it into Confluence, potentially saving me weeks of work.

Which brings me neatly on to:

• Automate as much as you can.

This means using export tools in your current location (e.g. wikis, CMS, document repositories, etc), and also Confluence's excellent built-in Word import functionality.  There is a Universal Wiki Converter which is not supported by Atlassian because it's a 3rd party tool, but the fact that the link for it takes you to a place on the Atlassian domain should tell you they think it's useful.  It doesn't work on every wiki, but if it does work for your wiki it will save you a lot of time.  If instead of, or as well as, wikis you've got lots of Word documents to import, the Confluence Word importer is brilliant.  It's really good at importing formatting and layout, as well as features like tables, images, links, headers, footers and diagrams, and it's really quick to boot.  Oh, and it will create new pages every time there's a heading in your document, if you want it to, even down to being able to set the level at which new pages are created (e.g. it will create new pages every time it finds a Level 1 or Level 2 heading, but ignore any other heading levels).  The Word importer has saved me huge amounts of time. 

Before you start importing things:

• Plan your space structure before you move things in. 

It's pretty annoying having a structure set up and working only to find it doesn't scale to accommodate what you're transferring and you have to move things around again.  This is where a content person is really helpful if you're a technical person.  Content people are good at the structure and layout of large bodies of information, and we'll help you analyse the user needs and get it right.  Confluence's space and page structure is deceptively simple because this simplicity means it's very easy to create monolithic spaces with one massive list of alphabetically ordered pages.  But people don't connect information alphabetically, so creating a space directory, page trees and label taxonomy using the guiding principles of good information architecture will make it much easier for people to navigate.

• If multiple people are bringing stuff in, agree on common naming conventions, page structure, and labels.

There's no getting away from the fact that if a team of technical communicators will all have slightly different ideas about conventions and structures, then a motley crew of various resources will all have very different ideas about conventions and structures.  Even if all the people importing are technical communicators, and especially if they're not, set agreed standards for page naming conventions, page structure and labels BEFORE anyone imports anything.  Otherwise it'll require a massive remedial exercise later on to standardise everything, or if this isn't done, your Confluence instance will be a mess.

• On the subject of labels, use them to say where a Confluence page came from, e.g. wiki name, shared drive, SharePoint, or wherever.

If you've never gone through this kind of process before this might seem superfluous, but believe me, it's not.  No matter how careful you are when you're importing, you or someone else will want to check the original source because "it doesn't look right" or "I'm sure we used to have more information on this in the old system".

And while we're talking about it:

• Keep your old repositories for at least 6 months, just in case. 

Transfer them to a portable hard drive that an admin locks in a secure cupboard if necessary, but don't "move and delete" because you'll regret it (even if no-one needs the back up you'll always be fretting that someone will need the back up).  If after 6 months (or whatever time frame you're comfortable with) you haven't needed the back up, get rid of it.  But in the meantime, keep them so that you can answer queries about "it doesn't look right" or "I'm sure we used to have more information on this in the old system" (see above) and so that you can do "idiot checks" to make sure you've got everything.  Pro tip: Every time you import something, move the original to a new location that mirrors the structure of the original location.  That way you can be sure everything's been imported.  If you can't realistically move it, mark it with (something like) an underscore at the beginning of the title.  This is also helpful when multiple people are importing things as it stops people importing the same thing twice.

Despite the fact that you're keeping your old repositories for a while:

• Bring as much metadata over as possible, especially who last edited [whatever you're importing] and when.

When you create a page in Confluence, your name is sat under the title as the creator.  This isn't useful for people who want to ask questions of whoever created the original content.  Pull the metadata from wikis or documents (manually if necessary) and add it to the page, preferably in a default location such as just under the title. 

Having said that:

• Consider adding smaller documents as attachments rather than extracting the contents. 

This will greatly reduce your import time and allow you to turn off your old system much quicker.  You can then turn the attachments into actually pages over time if you want to.  I wouldn't advocate using Confluence as a document library because really it's very poor at that.  But in terms of speed, you can drag and drop multiple documents at once into the Attachments page (or the Attachments macro) and if you're pushed for time to remove things from the old system this will work as a temporary measure.

Finally, a couple of "human" issues:

• Manually porting things over can be boring and a lot of people won't do it right because of this.  Only get people who really enjoy doing this kind of repetitive, finicky work, otherwise you'll spend huge amounts of time correcting the work of people who got bored 10 minutes after they started.
• As soon as you can turn off the old systems, do it.  Or at least restrict access to them.  People are creatures of habit and lots of them will keep using the old systems until it's literally not possible,
• It's going to take longer than you thought.  Take a deep breath, settle in for the long haul and don't get downhearted.  You can and will do this, and it can and will be a success.