Use Confluence to version control Office documents — best practices

Info type: How-toApplies to: Any reasonably recent version of Confluence, and any Microsoft Office documents (such as Word DOCX files).Good for: When you want to attach Microsoft Office documents to Confluence pages, so that you can keep related information together and get the benefits of basic version control.Assumes: Basic familiarity with Atlassian Confluence and Microsoft Office, and some knowledge of co-authoring and check-in/check-out features in Office 365. Also assumes that all contributors can wait until they are online to edit the document.

Use Atlassian Confluence right and you can manage information much better than you ever could with an old-school mess of stand-alone documents on a server. But there are times when you really are forced to work on a Microsoft Word DOCX file or similar. Here’s how to use Confluence to help you take some of the pain out of it.

First, any time you and your colleagues need to work on a typical office document* together, you’ll save yourself a lot of pain if you establish and stick to a ‘single version of the truth’. This means that no-one should make and circulate copies of the document (as email attachments, for example). Instead, instill practices and use tools that help everyone to identify and work only with the ‘master copy’.

Confluence helps to facilitate this as it offers:

automatic version control — so you can always review or retrieve earlier iterations of your document if necessary

an environment that you can use to help people find the ‘single source of the truth’ — no need to send conflicting email attachments back and forth, no need to download/upload the latest version

co-authoring on some Microsoft Office file types (assuming your workplace is also set up to take advantage of Office 365) — multiple contributors can work on the document at the same time

For the most part this is all easy to use in Confluence, but there some pitfalls to avoid.

*By typical, I mean the common ‘monolithic’ approach to documents with binary file types such as Microsoft Word DOCX files. An alternative to the traditional monolithic approach is to use other technologies in which you handle the content of documents as more flexible chunks of text, in much the same way as programmers handle code for software — the ‘docs as code’ concept. But this concept has a long way to go to become truly mainstream — a subject for a post some other time perhaps.

Create a new Confluence page somewhere sensible, as normal. Give it a clear title that will make it easy for users to associate the page with the document you’re about to attach. To make things really clear to everyone, make a note in the page like “See Attachments, and edit the work-in-progress (WIP) version via the Edit in Office link.” (I’ll explain all this more below). Then save the page.

You could add more to this page later — it is a good place to keep notes that relate to the document (and any further attachments), or to provide further guidance to colleagues who will contribute in some way.

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 the next steps.

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.

It can be a good idea to add Labels (tags) to your uploads in the Attachments page, especially if you will add a number of different attachments to keep related items together. Labels can be helpful for clarity and also to act as ‘hooks’ for Confluence macros later. For example:wip — to identify master work-in-progress copyinput — to indicate contributory/reference files you need on hand but are not actually working on directly
Confluence will only accept labels in lower case text, with no spaces (you can use hyphens instead, but aim for short labels).

You can also edit the Properties to include a comment like “This is the master work-in-progress file” or “This is source material, for reference only”. But, 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.

Edit the version-controlled document

VERY IMPORTANT: When you want to work on the document, do not click on the filename and download the file. Instead, click on Edit in Office. Your web browser will prompt you for a confirmation or two, and then your file should open directly in the relevant Office program. 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.

Be warned — if you don’t educate contributors about the importance of Edit in Office and get them to habitualise their use of it, you won’t get the benefits of this article. Instead you’ll experience the usual frustration and wasted time when you are forced to arbitrate and manually merge differences between binary document copies (for DOCX files, Word’s Compare and Merge tool is some help in the extreme — but it is best to avoid this situation altogether).

Edit as normal.

Users can Save progress as normal, but Confluence records a new version only when a user does a Check-in of the document (Office programs have a menu item for this, and they also prompt the user when they close the document/program).

Co-authors can all edit at the same time, and can Refresh at any time to receive each other’s edits.

Sending a copy out for review by email (if you really, really must)

Come review time, the best thing by far is to continue as I explained above — discourage copies and direct everyone’s attention to the single source of the truth. It is in everyone’s interests to work with the master copy in Confluence 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, the culture and limitations of your workplace may force you to circulate the latest version as an email attachment, at some point. Thus you’ll be forced to deviate from the single source of the truth methodology. Groan!

When this happens, I suggest you do as follows to limit the pain a bit:

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).

Manually append the file version number† to the filename of the downloaded copy. For example, N1234_ThisIsAFileWithPascalCaseFileName_v3.docx. Thus, even if later events and delays lead to confusion, at least you can check your Sent mail folder later to remind yourself what version of the master copy you originally shared!

†To get the current version number: In the Attachments page, click the ‘twisty’ arrow (highlighted yellow, 1) — Confluence lists the versions with their numbers, with the latest version at the top (2).

Confluence attachment version history.

It can quickly get messy once when you have a number of reviewers making different (and often conflicting) edits and comments on different isolated copies. Do what you can to limit the worst excesses. Good luck!