After a tumultuous and slightly short-lived affair with Sharepoint, I was introduced to Confluence and I was quickly won over by its simplistic UI and text editor. However, three years later I’m starting to feel disillusioned and frustrated with it. Here are some of the reasons why:
1. Bloat
Confluence has become bloated. I’m not sure if it’s a result of popularity or customers’ demands for new features but the feature set has been bloated while the basic functionality is neglected. It’s like a pet dog that has become fat and lazy from too many treats.
Confluence now and Confluence before …
2. Bugs
Any frequent user of Confluence will be aware of the numerous bugs that seem to go unfixed for long periods of time. We encountered a bug last week where images were breaking when copying a page (we later discovered this was caused by the image name having a colon).
Another common bug, which has caused me grief in the past, relates to being unable to export pages as PDFs for various reasons. This case, first reported in 2014, is still affecting customers two years later: https://jira.atlassian.com/browse/CONF-34275
An example of customer frustration…
3. Plugins
To do anything useful or practical with the vanilla version of Confluence you need to install expensive plugins. Want to use versioning? You need buy a plugin. Want to translate your content? You need to buy a plugin.
Even “Atlassian Verified” plugins don’t seem very reliable and are often costly.
Apart from the additional costs, my main issue with this is only a handful of plugins are built and maintained by Atlassian so you either have to take the risk of using a free plugin that will break in the future or you have rely on a third party developer to continue supporting it to ensure it works with newer versions of Confluence.
4. Basic Missing Features
The basic text editor in Confluence, the thing at the heart of the software, is still pretty poor and even things like basic formatting are a chore unless you manipulate the CSS.
It amazes me Confluence still doesn’t offer other fonts or the option to change the font size.
Off the top of my head, the things that annoy me include: you can’t insert certain macros directly after another macro or a table because they will break or it will mess up your formatting, you can’t create a table without borders (unless you have Source Editor), you can’t choose different fonts or font sizes (unless you import them in the CSS), you can’t change the background colour, you can’t justify your text and you can’t remove historical attachments that have been uploaded to a page in the past. These are all things I’ve just accepted as Confluence-isms, things you just have to accept that Atlassian aren’t going to fix any time soon.
5. Cost
Despite all these things, Confluence is not cheap. If you’re a company with 100 or more employees, the Cloud version will set you back 3,000 dollars (£2,419) each year:
Ouch: Confluence is not cheap!
On reflection, it’s pretty scandalous how much they are charging when so many bugs still exist, basic text editing functions are missing and most companies will need to install and pay for further plugins to get it to meet their requirements. Unfortunately, until someone comes up with a decent alternative I don’t see things changing.
Have you found a decent alternative that can be used for wiki content or software documentation/online help? If so, please let me know!
I’ve been using Atlassian Confluence for several years now and I think it’s an incredibly fun and useful tool when it comes to creating a wiki or online help. The list below includes useful hints, tips and time-saving shortcuts when using the software:
1. Watch the Atlassian Tutorials
If you’re a total noob and have never used JIRA or Confluence before then a great place to start and learn the ropes is to watch Atlassian’s tutorial videos on YouTube.
There are introductory videos, some with a slight Australian twang, which explain the general concepts and the basic Confluence hierarchy of child pages, parent pages and spaces. These can be found here.
One of the most useful videos, How to Build a Kick Ass Confluence Page, introduces a number of key features such as using macros, images and columns. This can be found below:
2. Using the Shortcuts
There are multiple shortcuts that can be used to make working with Confluence more efficient. The most useful is the { macro shortcut (called a “brace” in US or “curly bracket” in UK). Macros are tools which offer functionality to your page. These include a page tree, inserting a PDF, creating a panel, etc. Typing a letter will bring up macros names beginning with that letter. Other shortcuts include:
e – opens the edit screen. // – allows you to select a date from a calendar pop-up. @ – mention a colleague. [ – add a link to another Confluence page or an external link. w – will make you a watcher of the page. Ctrl + Shift + e – will open the preview of the screen.
To view a summary of the shortcuts click the ? help key while in edit mode. Alternatively the full list can be found here.
3. Working with Tables
Tables are a great way to add images and align them with text. See example below:
These can be added using the table button and dragging to select the required size. Alternatively you can press Ctrl + Shift + I to create a table.
To remove table borders, open the source editor using the <> button (this will need to be enabled in configuration) and enter the following:
A great way to highlight an important piece of text or information and break up long pieces of writing is to use the Confluence note, warning, tip and info boxes. These can be created using the following shortcuts:
{note
{tip
{warning
{info
These will appear as shown in the screenshot below. Any important text can be added inside the panels in the edit screen as normal.
5. Exporting Pages in Different Formats
If there are certain pages that a consultant or colleague in sales wants to show to a client or external partner who can’t access Confluence, it is possible to export them as Word or PDF documents.
To do this, go to the top right hand corner of your screen, click the menu icon and select the required action:
Clicking either ‘Export to PDF’ or ‘Export to Word’ will start a conversion of the page which will be downloaded and saved to your machine. The header and footer of the downloaded PDF can be customised in configuration.
6. Watchers, Shares and Mentions
If you want a certain user or group of users to read a page you have created or edited, this can be done three ways:
Watchers – watchers can be added and managed using the menu on the right hand side. Any users set as watchers for a page will receive email notifications when it is published or edited. This can be turned on and off using the “Notify watchers” Boolean flag at the bottom of the screen.
Shares – another way to inform Confluence users that a page, such as release notes, has been published is to share the page and manually enter the users names. They will all receive an email in the same way watchers do.
Mentions – if a user is mentioned in a page (using the @ macro) they will also receive an email notification. This is a direct but effective way to get users to read the content of a page.
7. Using Space or Page Templates
If you know you’re going to be creating a lot of similar pages where you want the content in the same format and layout then it might be worth creating a template. I only use templates for release notes but they are a great time saver.
To use a template, click the ellipsis button (…) but select the required template:
8. Reordering Connected Pages
If you’ve created the skeleton of your Confluence space and you want to amend the order of your pages, this can be done by clicking the Reorder Pages button:
This will open a new window. To reorder the pages, click the arrow to expand the full hierarchy of the pages and click and drag the page names to the required positions. Dropping a page onto another will turn it into a child page of that page.
9. Creating Anchor Links
It is possible to create an anchor link to a section of content on the same page or on another page. To do this, you can user the anchor macro:
Type {anchor and then enter the name of the anchor. E.g. Banana.
If you want to link to this anchor from the same page, simply add a link using the link button, selected ‘Advanced’ and enter the anchor name with a hashtag # E.g.#anchorname.
Linking to another page is a bit more tricky and will require the full name of the page, followed by the page name and the anchor name. See format below:
If you work alongside a development team using Atlassian’s issue tracking tool JIRA, there is a great way to quickly create release notes in Confluence using the JIRA filter macro.
To use this type ‘{‘ and then ‘JIRA‘:
Next, using JIRA Query Language (JQL) in the search bar it is possible to filter for cases by JIRA project, release version, issue type etc. The example below shows the JQL for all cases that are new features linked to a project called “APP2” with version number “2.o1”:
project = APP2 AND fixVersion = “2.01” and issuetype = “New Feature” ORDER BY issuetype DESC, due ASC, priority DESC, created ASC
When inserted into a table, the release notes will appear as follows:
The columns (issue type, key, summary, reporter, assignee or status etc) can be altered by clicking Edit on the filter. Next click Display Options to view the editing options.
Begin typing to add more columns or click the ‘x‘ to remove specific columns.
To change the order they appear in open the source editor using the <> button and in search for “columns” and manual rearrange the order of the column names. See highlighted section below:
By using tables with filters for each issue type in a template page, it is possible for the release notes to literally populate themselves as the JIRA cases are added to a live project. By using this method for the products I work on, apart from editing the case names if they aren’t clear enough, the only documentation I need to write is for new features and cases where functionality changes or new settings have been added. It’s not only a great way to save time but it also ensures no JIRA cases are ever missed.
