Tag Archives: Atlassian 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!

10 Tips for making Content more Engaging

I’ve always liked to learn new bits of software by trial and error, trying things out for myself first and learning from my mistakes but there’s only so far you can get before you get stuck. This is why documentation and help are so invaluable because a piece of software is worthless unless you know how it works.

1c00898.jpg

In today’s fast-paced world, people don’t have time to read chunky 900 to 1000 page manuals, they want information to be quick and accessible. As a result, technology companies and their technical writers are having to adapt their techniques and content strategies to make documentation more exciting and engaging for readers.

Here are some of the best ways to keep people interested in your content:

1. Pictures

As you have probably seen from my blogs, I am a real advocate for using good images to break up text and make documentation more approachable and more visually interesting.

2016-05-20 11_32_36-Mozilla Support.jpg

This is just the Firefox help homepage but as I mention in my blog last week, I thought the design and use of imagery was really visually appealing.

2. Videos

Taking this approach one step further, videos are another brilliant and effective way to engage help users as long as they are well put together, short and succinct.

The example above is one of Skype’s excellent video tutorials which are really well produced.

Videos can be made with software such as Camtasia or free tools such as Open Broadcaster Software.

3. Gifs

Like videos, it is possible to add gifs to make your content more dynamic and visually interesting. They are a quick simple way to show an example of how something is done:

Animation

This gif was produced using free open-source software called ScreenToGif.

4. Infographics

I think graphics are a great way to get a lot of information across to your readers in one image if they are designed well.

all-about-spotify-and-ecosport_527a5b85c6af0_w1500

The Spotify infographic above has 10 separate facts spread across one image.

5. Examples

Using examples is the best way to show your readers what you are trying to explain.

2016-06-02 14_05_27-Embedding a Tweet on your website or blog _ Twitter Help Center

On the page above, taken from the Twitter, the help describes how to embed a Tweet and then gives examples.

6. Be Human

Use an informal or conversational writing style. Write as if you were describing how the software works to a friend. Readers won’t engage with a robotic tone of voice.

2016-06-02 14_07_29-People You May Know _ LinkedIn Help

Linkedin’s Help addresses users by their first name to make the experience more personal.

7. Keep it Short

Don’t overwrite. If you can explain it in one sentence then write one sentence. It’s better to use 25 words rather than 250. The shorter the better.

2016-06-02 14_10_12-Login Basics _ Facebook Help Centre

Facebook’s Help Centre covers the login basics in just 73 words (and three links).

8. Keep it Simple

Don’t use lengthy words the average person won’t understand or that will get lost in translation. Go with “move in a circle” rather than “circumbilivagination” or “use” instead of “utilise”.

2016-06-02 14_14_05-Start

Sorry Royal Mail but I really dislike the use of “utilise”, it’s just a waste of four letters!

9. Easy Navigation

If your help system is easy to work your way around then people will want to use it.

2016-06-02 14_20_59-Start

Skype’s Help is really easy to navigate from my experience. You can check it out here.

10. Make it fun!

Use humour and unusual text to catch people’s attention. This is discussed by Mozilla’s Michael Verdi in his presentation How To Write Awesome Documentation.

Atlassian Confluence’s help system, shown below, encourages new users to join a fictional space program and complete a mission:

2016-06-01 14_40_40-Get started - Atlassian Documentation

2016-06-01 14_40_57-Tutorial_ Navigate Confluence - Atlassian Documentation

Sure, it’s a bit wacky and off-the-wall but its fun, it catches attention and keeps readers interested and engaged.

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.