Category Archives: Confluence

Five Reasons I’m Falling Out with Confluence 

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.

160402182953-tease-overweight-dog-update-irpt-full-169
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

2017-03-19 12_43_51-Clipboard
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.

2017-03-19 12_59_12-Films & TV
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.

2017-03-19 13_20_33
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:

2017-03-19 13_24_50-New notification
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!

Atlassian Confluence: Hints & Tips

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:

Applebanana.jpg

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:

<table>
<tbody>
<tr>
<td style=”border: 0.0px;”>test </td>
<td style=”border: 0.0px;”>test </td>
</tr>
<tr>
<td style=”border: 0.0px;”>test </td>
<td style=”border: 0.0px;”>test </td>
</tr>
</tbody>
</table>

This example will create a 2 x 2 table of cells with no borders.

applebanana2.jpg

The code for this table is shown below:

<table>
<tbody>
<tr>
<td style=”border: 0.0px;”>
<ac:image ac:thumbnail=”true” ac:width=”25″>
<ri:attachment ri:filename=”apple.png”/>
</ac:image>
</td>
<td style=”border: 0.0px;”>Apple</td>
</tr>
<tr>
<td style=”border: 0.0px;”>
<ac:image ac:thumbnail=”true” ac:width=”25″>
<ri:attachment ri:filename=”banana.jpg”/>
</ac:image>
</td>
<td style=”border: 0.0px;”>Banana</td>
</tr>
</tbody>
</table>

4. Creating a Note, Warning, Tip or Info Box

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.

Notes2.jpg

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:

2015_Kick_Off__London__-_UK___BENELUX_-_Hoyster

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:

2015_Kick_Off__London__-_UK___BENELUX_-_Hoyster

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:

Who_is_who__-_UK___BENELUX_-_Hoyster.jpg

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.

Reorder_Pages_-_UK___BENELUX_-_Hoyster.jpg

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.

Edit_-_2015_Kick_Off__London__-_UK___BENELUX_-_Hoyster

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.

Edit_-_2015_Kick_Off__London__-_UK___BENELUX_-_Hoyster.jpg

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:

Confluencesitename.com/Spacename/Pagename#Pagename-Anchorname

10. Linking with JIRA to create release notes

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‘:

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:

2016-05-06 16_27_52-Photos

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.

columns.jpg

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:

column-order.jpg

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.