Better collaborative writing in Word, through version control with Confluence

Eric WestonProductivityLeave a Comment

Info type:
Applies to: Microsoft Word on an Office 365 subscription, plus Atlassian Confluence.
Good for: When your organisation has Confluence and yet you're forced to create a Word document.
Assumes: Basic familiarity with Confluence, Word and Office 365.

Got Atlassian Confluence, but you’re forced to collaborate on a Microsoft Word file? Here’s how to minimise the pain and stay sane.

I focus on Microsoft Word .docx files in this article, but many of the same points apply to other programs and file formats too.

The value of Confluence for collaborative writing

Confluence makes collaborative writing easier, in large part because it is a synchronous ‘online’ environment. This affords many benefits that don’t apply in asynchronous ‘offline’ environments (such as when people circulate Microsoft Word files as email attachments).

For example, each participant can see and respond to each other’s comments in real-time — and be notified of changes and ‘@mentions’, automatically. Thus it is easy to keep everyone in sync with the latest information — which is half of the battle.

But these benefits really only come to the fore because of an even more important point about the online environment of Confluence. That is, all collaborators work on the same single instance of a document by default (though it may be comprised of numerous individual pages within Confluence).

Having such a single source of the truth is invaluable. It cuts out many causes of frustration and wasted effort that are practically inevitable otherwise.

  • There is no doubt as to which file contains the latest iteration of the document.
  • Everyone who needs to can easily find and work on the latest iteration, at any time.
  • It is easier to reach consensus, because everyone is up to date and able to react and converse in real-time.

When you’re forced to work in Microsoft Word you lose most of these benefits.

The trouble with Microsoft Word and ‘collaboration by email’

You start a document in Word. You slave over the first draft. You send it out as an email attachment to get input. And… the email thread blows up with contradictory feedback, obscure discussions, ambiguous requests and various edited copies of your attachment.

How much fun do you have sorting that lot out?

  1. Answer A: It’s a barrel of laughs — let’s do it again soon.
  2. Answer B: It’s a royal pain in the neck — let’s please find a better way.

I very much doubt that you feel drawn to Answer A. So, let’s agree that ‘collaboration by email attachment’ is a bad method and that we’d all be much better off with a more efficient alternative.

There are also other difficulties that are fundamental to work based on binary file types such as Microsoft Word .docx files. But that’s a subject for another time.

How Confluence can make Word more bearable and replace email

If you have Confluence then of course it’d be better to draft your documents there rather than in Word. But if you really must use Word at some point, then you should at least take advantage of some handy features in Confluence to create a process that is less fraught with difficulty.

You want to encourage a culture in which people don’t make and circulate copies of documents. Rather, they should direct all their efforts at a single master copy (remember, you want a single source of the truth at all times).

Confluence can help to facilitate this as it offers:

  • An environment that makes it easy to find the master copy and to have conversations over it.
  • Automatic version control features — so you can always review or retrieve earlier iterations of your document if necessary.
  • Co-authoring features via Office 365 (if you have it) — so that multiple contributors can edit the document at the same time.

For the most part this is all easy to use in Confluence. But there some pitfalls to avoid and good practices to know — which is what the rest of this article is about.

Prepare and upload the document

1. Prepare the document for version control.

Get the document ready to upload. In particular, make sure that the file name of the document is ‘Web safe’.

Note: Web safe file names

Special characters in the filename can actually break functionality in many web-based systems, including Confluence — and unfortunately it isn’t always obvious when this is the cause of a frustrating problem.

You can read more about this elsewhere, and you might also like to try this tool to help you convert to a web-safe filename:

2. Create a new Confluence page.

To use the file versioning features in Confluence, you need to attach your file to a Confluence page. So, create a new Confluence page somewhere sensible, in the usual way.

Always make it easy for contributors to find things and to understand what’s what:

  • Give the new page a title that clearly relates to the file (or files) that you’re about to attach.
  • It’s a good idea to make a note in the new page, like “See Attachments, and edit the work-in-progress (WIP) version via the Edit in Office link.” (you’ll see why later in this article).

Save the new page.

Note: Making good use of the new page

You could add more to this page later — it can be a good place to add contextual notes as an aid to contributors and for other project management purposes.

3. Attach the .docx file to the new page.

From the new page, go to the menu (ellipsis button) and select Attachments. This is where you will find the file in future, after you’ve uploaded it in a moment.

Confluence ellipsis button and attachments menu item
Confluence ellipsis button and attachments menu item.

Use the functions on the Attachments page to upload (and thus ‘attach’) your document. You can browse and select your document file, or you can drag and drop — and Confluence will give you a chance to add some extra information.

Note: Labels

It can be a good idea to add Labels (tags) to your uploads in the Attachments page. This is especially helpful when you will add a number of different attachments — file names aren’t always adequate to avoid confusion, and labels can help you to group or disambiguate your attachments.

Labels also provide ‘hooks’ for Confluence macros, which can be very helpful.

Example: Use of labels

  • wip — to identify the master work-in-progress copy, as distinct from any other copies you might be using for reference purposes
  • input — to indicate other files that contain information you might need but which are not actually part of the drafting effort

Note that Confluence will only accept labels in lower case text, with no spaces (you can use hyphens instead, but aim for short labels).

Note: Properties

If a label is not enough, you can also edit the Properties to include a note like “This is the master work-in-progress file” or “This is source material, for reference only”.

However, be mindful that Confluence will repeat the same the comment for every version thereafter unless you change it manually! It won’t prompt users to adjust the existing comment when they check in a new version.

So, don’t use Properties to add notes that only make sense for a specific version of the document.

Edit the version-controlled document

1. Edit the master copy only, online.

Click on Edit in Office. Your web browser will prompt you for a confirmation or two, and then your file should open directly in Microsoft Word.

Only by doing it this way will you be able to (a) save directly to the version controlled master copy and thus maintain your single source of the truth, and (b) have access to the co-authoring feature.

Caution: Discourage downloads and encourage use of the ‘Edit in Office’ link

If a user simply clicks on the document filename then they will be prompted to download a copy of the document that they are free to edit in isolation. You don’t want this, for the reasons already stated in this article.

So, be sure to educate participants about the importance of the Edit in Office link.

2. Edit the document.

Edit as normal, within the co-authoring environment.

Note: Co-authoring basics

  • Co-authors can all edit at the same time, and can Refresh at any time to receive each other’s latest edits. (Word offers a button on the Ribbon menu for this.)
  • Users can Save progress in the co-authoring mode just as they normally would — this does not create a new version.
  • Confluence will record a new version only when a user does a Check-in of the document. (Word offers a button on the Ribbon menu for this, and it also prompts the user when they close the document/program.)

How to send a copy for review by email (if you really, really must)

Come review time, the best thing by far is to continue as I explained above. If at all possible, discourage copies and direct everyone’s attention to the master copy in Confluence at all times.

It is in everyone’s interests to work with the master copy as the only copy. Encourage your contributors and reviewers to keep all the action in this one place — educate them on the procedure and its benefits, and make the document easy to find (don’t hesitate to share the appropriate URL, even if you think that people shouldn’t need help to get to the right bit of Confluence).

However… in practice, in spite of all our best efforts to avoid ‘collaboration by email attachment’, the culture and demands of your workplace may yet force you into it at some point.

Thus you’ll be forced to go ‘old school’ and deviate from the single source of the truth methodology after all. Groan!

However, hopefully by this point you’ve cleared most of the hurdles and you only need to circulate the document for approval. Still, the document may yet elicit more feedback than you had hoped would be necessary. So, I suggest you do as follows to pre-empt this and keep some sanity:

1. Download a copy to circulate.

Go to the Attachments page as before, but this time click on the filename (to download a copy of the document file to your computer).

2. Append the version number to the filename.

Manually append the file version number to the filename of the downloaded copy. For example, X123_PascalCaseFileName_v3.docx.

Do this so that even if (when) there is confusion later, at least you can check your Sent mail folder later to remind yourself of which version of the master copy you originally shared! This can make it a little easier to unpick a mess when people return edited copies that are out of sync with changes to your master copy.

Note: How to find the current version number

In the Attachments page, click the ‘expand’ arrow (highlighted yellow, 1) — Confluence lists the versions with their numbers, with the latest version at the top (2).

Confluence attachment version history
Confluence attachment version history.

3. Circulate the copy (and freeze the master copy).

Write your email, attach the copy of the document file and circulate in the usual, traditional way.

If possible, ‘freeze’ activity on your master copy at this point so that it does not get out of sync with the copy you circulated. Out-of-sync changes tend to complicate things further, so if you can, wait until you’ve collated all feedback.

When you have participants who edit isolated copies of the document it can get messy, fast. Do what you can to limit the worst excesses. Good luck!

Caution: Educate participants to not upload their copies

If anyone uploads a copy to the Attachments page where you store your master copy, one of two things will happen:

  • If the file name of the upload is exactly the same as the file name of the master copy, then the upload will become the latest version. This means that any changes made on the master copy in the interim will be missing from the latest version. This can take a lot of effort to fix, especially if edits are ongoing while you’re trying to unpick the mess.
  • If the file name is not exactly the same then the upload will become another file under version control in the Attachments page. There are use cases in which you might do this on purpose (in which case, be sure to assign clear labels). But more often it is a mistake that leads to confusion.

This article is a substantial rewrite of an earlier version first published 2019/09/23 under the title “Use Confluence to version control Office documents — best practices”.