Seven Major Pitfalls to Avoid When Using Atlassian Confluence for Collaboration

13 min read /

Here are seven common mistakes made by organizations using Confluence for collaborative knowledge management and documentation – and how to avoid them.

The following list applies to Confluence – Atlassian’s collaboration platform and enterprise wiki – but may be relevant for other platforms and content management tools, too. The same issues keep cropping up – so let’s find out how to fix them.

1) Excessive Access Restrictions

After setting up a collaboration platform, many admins take steps to restrict user access. If multiple target groups are using the platform heavily, these restrictions may be necessary. But when you’re just starting out with a knowledge platform, intranet or documentation management system like Atlassian Confluence, you must actively encourage your users to keep reading and contributing to your content. Don’t leave them out in the cold.

Excessive restrictions may result in some users inadvertently being unable to view content that their colleagues can access at will – to name just one potential source of friction. People will start feeling excluded and become frustrated – the opposite of what you want to achieve.

How to fix this

Consider the wiki approach to collaboration platforms, where openness is key. Give users the freedom to view and edit as much as possible, and limit access only when truly necessary. You’ll soon notice that users will gravitate towards the content that matters to them, ignoring resources that aren’t relevant to their work. And they’ll never feel excluded again.

2) Multiple Users Sharing One Account 

Some Confluence admins think it’s a good idea to give casual users a generic user account, such as “Support Agent”, that’s valid for multiple users or groups. They reckon this approach saves ‘precious’ Confluence user licenses and is easier to administer, due to the lower number of users.

But this strategy entails security risks due to shared passwords – and it impedes collaboration, too. We want to encourage Confluence users to become regular and active participants – not just casual visitors. And if a user makes a key contribution to the organization’s Atlassian knowledge platform, that user deserves – and will appreciate – personal credit for their efforts.

Generic accounts make your users practically anonymous. Before long, they’ll start acting that way, too – and so will other users: “Oh, another edit from a random support agent. Don’t know, don’t care.”

You can almost guarantee that generic user accounts will hinder collaboration. It’s impossible to trace who has made edits or authored newly created pages. Transparency is one of Confluence’s unique selling points – but by using generic accounts, that advantage is completely negated. 

What’s more, Confluence’s social features – such as likes, and favorite pages and spaces – are rendered almost useless. Users are unable to express their personal preferences and interests.

How to fix this

Well, this one’s easy: Never use generic accounts. If administrators want to manage settings for similar Confluence users, they should create and administer groups instead. This approach also eliminates vandalism, as you can trace every content edit back to specific users.

3) Disabling the Comments Feature

Collaboration means communication – and collaboration platforms such as Atlassian Confluence enable your team to interact with ease. And written text is the simplest way of sharing your thoughts online quickly and effectively. 

By default, Confluence allows users to leave page comments or inline comments on each page or blog post, so they can share feedback with authors and editors. If a discussion develops below an article or Confluence page, it’s a sign that the content asset is worth talking about. And even more critical comments can be seen as an invitation to improve your content.

If you disable this functionality, you’ll destroy the most important social interaction feature of your collaboration platform.

How to fix this

Another easy solution: Just allow (and invite) Confluence users to comment on pages and blog posts. By doing so, you show that you’re open to insights, user discussions and ideas from outside the editor circle. Inline comments can be used to provide really precise feedback. In some cases, it might even be a good idea to allow anonymous users to comment on publicly available Confluence pages – actively encouraging readers (and customers) to provide feedback.

4) Neglecting Confluence Updates and Performance

Users demand – and deserve – a highly available, secure and up-to-date system. Your platform needs a fast and responsive user interface that’s fun to work with (and waiting for a page to load is no fun at all). If everything’s running smoothly, word will soon spread – and before you know it, you’ll have legions of enthusiastic Confluence users interacting with your platform.

New systems should be sleek, easy-to-use and – of course – faster than the previous solution. Confluence certainly fulfils the first two criteria, but it’s down to the administrator to ensure exceptional system performance and security at all times.

How to fix this

If you're hosting Confluence on your own servers, ensure you’re using the latest version of Confluence, and do whatever it takes to guarantee your Confluence server performs rapidly and reliably. Plan for the ‘worst-case scenario’ – which, in fact, will be the best-case scenario for collaboration and user engagement. Even if your platform has thousands of users and pages, your Confluence should be bang up-to-date and deliver lightning-fast response times.

Better yet, go the Cloud route. Confluence Cloud is quick to start up, easy to work with from anywhere, and helps your team avoid the strain and added costs of installation, maintenance and support. 

5) Putting Everything on One Page

Your Confluence users should all be ‘on the same page’ – but that doesn’t mean you need to post all of your documentation on a single page with thousands of lines of content.

A few enterprise wikis, such as Confluence, provide out-of-the-box content management functionality that allows you to organize content into defined collections called spaces. Within a space, you can define as many pages and subpages as you like.

This allows knowledge workers to create content in the same way that we process knowledge in our brains which is more structured, similar to chapters and sections of a book.

If pages are too long, and readers need to keep scrolling to assimilate all the content, they’ll soon lose the motivation to keep reading. Lengthy pages also hinder the commenting process – it’s very difficult to leave a comment on a phrase that appears 10,000 pixels away. In addition, large content assets cannot be reused properly.

How to fix this

Split long pages into subpages, and check the length of frequently updated pages regularly to prevent ‘bloating’. Here’s a rule of thumb: If a page uses three or more heading levels, consider creating smaller chunks that can be reused, e.g. by using Confluence's Include macro.

When importing content from a Word document, select “Split by heading” to apply the document’s structure to Confluence page hierarchies.

To make your Confluence space’s complex page structure clear to readers and authors, make use of the navigation sidebar which displays the page hierarchy.

Go a step further with our app Scroll Documents which enables your team to define a Confluence page tree as a single unit and perform advanced actions like versioning, change tracking, copying, and more. These defined documents are also accessible from a dedicated document library to make sure they're always within reach from one easy place in your Confluence space. 

6) Working Offline, and Copying/Pasting into the Editor

For people like me who work with Confluence every day, it’s hard to understand why some casual Confluence users think it’s more efficient to “check out” content from the knowledge base, copy it to their computer’s word processor, then paste their edited version back into Confluence before hitting “Save”. If, for instance, you’re editing a page or blog post during a long plane journey with no internet access, this approach makes sense – but if you’re at your desktop, it’s just illogical.

If you keep the page in edit mode during editing, you can see changes made by other users immediately. But if you are editing content externally, other users might update the page in the meanwhile – and merging back external changes is no fun. And even if you’re able to merge it all together, rich formatted content pasted from Microsoft Word etc. often contains a great deal of formatting clutter. This could result in awkward editor behavior, misleading styles, and errors in publishing or exporting to other formats. 

How to fix this

To remove external formatting clutter, such as incorrectly-colored text in the Confluence editor, select “Clear formatting” – you can find this option on the toolbar, within the strikethrough drop down menu. And for incorrect formatting that’s tricky to fix, for instance in more complex lists, the Confluence Source Editor plug-in allows authors to edit a page’s storage format.

7) Storing Content as an Attachment

It’s easy to import content from a Word document – but it’s even easier to attach that document to a page. In fact, Confluence handles attachments very smoothly. You can even display the contents of a Word or PDF document on a page, and the Confluence search function indexes text within those attachments. But shovelling documents from one system to another can indicate a lack of a defined content strategy. 

This ‘piggyback’ approach of storing content in attachments contradicts the way Confluence has been designed. It wasn’t primarily intended to be a document or asset management system – it’s first and foremost a collaboration platform and wiki where authors create and manage native Confluence content (i.e. pages and blog posts). 

How to fix this

Use the graphical Confluence editor to create and edit content, and you’ll benefit from Confluence’s collaboration features – such as the ability to track changes, comment on content, and share information. If you need to provide users with offline documents (such as PDF or Word files), you can use our Scroll Exporter Apps to export content as custom, professionally-styled documents.

Want to Get More Agile in Your Confluence Collaboration?

Confluence is a great collaboration platform and wiki, but it takes more than a great tool to ensure successful knowledge management. Remember that it depends heavily on the people who use it and how much they love their collaboration platform, and how they can benefit from the content provided there. This is vital to making your collaboration platform a success, and motivating users to contribute and share their knowledge.

There's also more to writing than typing words into an editor. You need a plan and a process. Here are our guidelines for managing your team's documentation work in an agile environment:

Learn more about agile documentation and Confluence best practices on Rock the Docs.
Check it out