Category Archives: Blog

UX Design: The Good, the Bad and the Ugly

The Good

One of the nicest pieces of UX design I’ve come across recently is the Monzo banking app. When a friend from university said he was part of team setting up a bank it piqued my interest, partly because it sounded so ambitious and partly because I worked in the payment industry at the time.

monzo_horz_lightbg

Founded in 2015 as Mondo before a legal dispute forced them to change the name, they are part of the new crop of so-called “challenger banks”, set up to battle the old guard of banking institutions who are losing touch with their customers, the smartphone generation in particular.

Their USP is that Monzo is built with the latest modern technology (developed in Google’s coding language Go) so is “as smart as your phone”, easy to use and is able to offer instant notifications when payments are made.

monzo-screen

spending

It’s difficult to convey how nice the UX is in a still image but the app is incredibly clean and intuitive and makes it a fun way to map your spending. As you make purchases on your Monzo card they appear instantly in your app where you can see the name of the merchant, the amount spent, as well as map location, the category that your purchase fits into (entertainment, transport, groceries etc) and it is possible to attach a receipt and a note, completed with emojis. Overall, it’s just a very pleasing app to use.

The Bad

One my tasks at work is to send out version releases and patches using a piece of software called BizWizard which is made in Sweden. I’m going to be brutally honest, the old version of the product really sucked and I dreaded using it because I had so many issues with it.

bizwizard_retina_660

For starters, it wouldn’t run on Google Chrome and would crash unless running with Edge or Firefox.  I also found that most of my time on Bizwizard seemed to be spent watching the same grey progress bar as it slowly moved from screen to screen:

bizwizard

I thought it might be related to the amount of messages being stored but it is slow to navigate between most screens, even those without much data. It just made the entire experience of using it very dull and frustrating.

I’m not going to be totally negative about Bizwizard because the latest version is a dramatic improvement and for the most part, it’s really easy to use. I just encountered one more issue that I didn’t like in the new version of the content editor, which is that when I finished writing a message, my natural inclination was to click the prominent blue Revert button at the bottom of the screen, assuming that was the Save button (See screenshot below):

bad-ux
The Revert button which tricked me into thinking it was a Save button in BizWizard.

It’s probably a result of using Confluence, where the Save button is in the button right (see below), but as a result of clicking Revert my text was wiped with no way to undo or get it back. Very frustrating as a first time user of the new version.

confluence
The Save button in Atlassian Confluence.

I suppose I can’t be too hard on BizWizard for creating a button in a similar style and position to Confluence but it shouldn’t have so much prominence because it is a more natural place for a Save button. I’ve sent my feedback to them so it’s up to them whether they change it or not.

The Ugly

Linkedin is actually an app I use quite a lot and occasionally use to share my blog posts but unfortunately there are quite a few things I don’t like about it and the overall experience.

linkedin

Apart from the feeling that the “professional network” is striving to turn itself into Facebook and forever tries to force connections on you, there are other things that annoy me and just make it an unpleasant and sometimes annoying user experience.

Take the homepage for example, there is just so much going on. It’s just a bit of an information overload and makes me want to close it down. See screenshot below:

linkedin-2

There are so many things that demand your attention here in my opinion, with the orange warning bar about emails at the top, the yellow button begging to be pressed so I can reconnect with colleagues (not today thanks), blue links encouraging me to improve my profile and grow my network, an advert asking me to try Hired today, and a tab informing me I have one new update (and that’s having already read my notifications). It’s just far too much, like a needy kid screaming for attention, a lot of it just unnecessary and off-putting. It ruins the user experience.

In contrast, the smartphone app version is actually really nice to use and much cleaner than the web version. It’s a much more enjoyable user experience with a nicely designed UI and much less information to deal with. See screen below:

linkedin23

The only negative is the red notifications are often unclear so I don’t always know what I’m getting notifications for and there still seems to be an ongoing issue with messages/emails,  for example receiving and sending duplicates of the same message.

As a technical author I do find myself looking at software and applications through the eyes of a first time user/ tester so I’m maybe I’m being harsh with my criticism but development teams should always consider the user, their experience and how they would expect or like your product to work. If your product doesn’t work how they would expect it to, if they find it difficult to navigate or if they find the overall experience annoying or frustrating then they are unlikely to want to use it again and that’s bad news for business.

Please note: User experience is always going to be subjective so some people may agree or disagree with me about these examples. It goes without saying that all of the opinions above are my own and not those of my employer!

The Basics of JavaScript

For the past month or so I have become somewhat immersed in JavaScript. As I already knew the basics of HTML and CSS through using WordPress and other CMS tools, I took the plunge and started to learn JavaScript, the other core web development language, using Codecademy and w3schools.com.

What is JavaScript?

JavaScript is an object-orientated programming language that is derived from C + +. It is a scripting language normally used to create interactive effects within web browsers. JavaScript’s dynamic capabilities include run-time object construction, variable parameter lists, function variables and event loops, some of which I will discuss below.

JavaScript Syntax & Operators

Variables are containers for storing data values. These are declared by the var keyword:

Var

Functions are used to perform defined tasks. These are declared by the function keyword.

2016-08-25 14_30_35-Introduction to Functions in JS _ Codecademy

A function will only be executed when it is called/invoked. e.g. In this case the function is called “greeting” so the input below will return “Great to see you Dave”.

greeting ("Dave")

Return is a statement used to stop the execution of a function. It will also return the value of a function.

var x = myFunction(2, 4);        

function myFunction(a, b) {
    return a * b;                
}

In the example above, x will be returned as ‘8’.

Console.log commands are used to display data . Console.log() will take whatever is inside the parentheses and log it to the console.

2016-08-25 16_27_53-Getting Started with Programming _ Codecademy

In this case, the information logged to the console will appear as:

2016-08-25 16_29_59-Getting Started with Programming _ Codecademy

If/else statements are used to make decisions in the code. An if/else statement will execute one block of code if a specified condition is true, if the condition is false, another block of code can be executed.

if-else

Loops are used to execute a block of code a number of times. Loops are useful if you want to run the same code repeatedly with different values. It’s all about getting the computer to do the legwork for you, as opposed to typing out numerous lines of code.

Here is an example of a for loop. This will run 5 times, with values of ‘step’ 0 to 4.

var step;
for (step = 0; step < 5; step++) {
  console.log('Walking east one step');
}

Different loop types include:

for – this will loop through a block of code a number of times.
while – this will loop through a block of code while a specified condition is true.
for/in – this will loop through the properties of an object.
do/while – this will also loop through a block of code while a specified condition is true.

Arrays are special types of variable that can used to hold multiple values at one time.

For example, if you wanted to list a number of values from one array you could use a block of code like this:

var beers = ["Heineken", "Amstel", "Carling", "Fosters"];
for (var i = 0; i < beers.length; i++) {
console.log (beers [i]) ;
}

This would return:

Heineken
Amstel
Carling
Fosters

Funny Typos & Spelling Mistakes

We all make mistakes every now and then. Sometimes they are made by the developers, sometimes they are made by the technical authors or content writers. Here are a few examples of unfortunate typos which serve as a funny reminder to always double-check your copy before it is released!

1. The existential crisis. Are you sure you want to exist?
nFqVG4N
Credit to Reddit user /u/psychob

2. Shit happens. A really unfortunate misspelling of shoot by Pentax.

3szEjQe

3. Beyond parody. British Government announces new language test for migrants with an embarrassing misspelling.

u-k-english-requirement-announcement

One of the first people to spot the mistake was Nick Wallis from BBC’s The One Show:

4. Child’s Play: It’s important to know the difference between “they’re” and “their”.

creative_kids_software

5. Regsiter? Nah, I think I’ll register with a company which doesn’t make spelling mistakes.

hubspot-typo

6. Reeding between the lines: I don’t think this Yellow Pages advert was proofread.

Proofreading

As the examples above show, we’re all human and mistakes do happen but they may cost your website, business or documentation their credibility and sometimes money. Always double-check your copy before publishing it.

The Origin of the Hamburger and Other Icons

The emergence of the three-lined “Hamburger” menu icon in modern interface design was so fast I had just assumed it was a relatively new creation. However, after a bit of research I discovered its origins were far more rooted in the history of technology than I first thought. It was software designer Geoff Alday who made the discovery, which he wrote about in this blog post, learning that icon was first used back in the early 1980s on the interface of the Xerox Star work-machine, one of the grandfathers of the modern personal computer. You can see it shown in the middle of the screenshot from 1981 below:

2016-07-07 16_19_22-Start
A bit-mapped screenshot from the Xerox Star workstation released in 1981.

Norman Cox, the designer behind the icon, said its design was meant to be “road sign” simple, functionally memorable, and mimic the look of the resulting displayed menu list. Cox later told the BBC it was jokingly referred to as the “air vent” icon. He said: “At Xerox we used to joke with our initial users that it was an ‘air vent to keep the window cool’. This usually got a chuckle, and made the symbol more memorable and friendly.”

“At Xerox we used to joke with our initial users that it was an ‘air vent to keep the window cool’. This usually got a chuckle, and made the symbol more memorable and friendly” – Norm Cox, former Xerox designer

The icon didn’t really appear for nearly 30 years until it was adopted as a menu icon by social networking site Path, which launched in 2010, and then later Facebook and Apple iOS applications, meeting a growing need for more content to fit onto smaller smartphone screens via the use of menus. It has since become widely-accepted as a menu icon by UI designers and can found everywhere from web browsers Google Chrome and Mozilla Firefox, to news websites such as the BBC and others.

2016-07-08 13_46_49-Photos-firefox

2016-07-08 13_47_24-Chrome

2016-07-08 13_51_08-Home - BBC News

2016-07-15 14_53_20-News, sport and opinion from the Guardian's UK edition _ The Guardian

After some more research I soon discovered that there were a number of other prominent icons and symbols still used today that first emerged in the 1980s. Apart from the ‘Hamburger’ icon, Norman Cox is also attributed with creating the document icon, which was another part of the Xerox Star interface. This image here shows the design development. After Cox, one of the most prolific designers of the 1980s was Susan Kare who worked for Apple Macintosh. Descendants of her early designs that still exist today include icons such as the lasso, the grabber, and the paint bucket. You can see some other the examples of her work in the screenshot below:

02_macicons
A selection of designs by Apple Macintosh designer Susan Kare.

She also came up with the command key design (⌘) that still appears today on most Apple keyboards. Kare apparently discovered it while browsing through a symbol dictionary and found it was commonly used on signposts in Scandinavian countries to mark places of interest. When asked by MacFormat magazine about the longevity of her icons she said: “I am very grateful and appreciative that some images I designed almost 30 years ago are still in use. I believe that symbols that are simple – not too many extraneous details – and meaningful can have a long life span.”

Other icons that have survived since the 1980s are shown in the table below:

  Icon  Name  Designer/Creator
menu-alt-512 Hamburger icon Norm Cox for Xerox Star.
ios7-document-icon Document icon Norm Cox for Xerox Star.
command-symbol_318-74882 Command icon Susan Kare for Apple Macintosh.
Susan-Kare-fill-icon-660x660 Fill icon Susan Kare for Apple Macintosh.
mouse-cursor-icon Mouse icon* Douglas Englebart for Xerox PARC
common-search-lookup-glyph-128 Search icon  Keith Ohlfs for NeXT Inc.

*The mouse cursor arrow originally pointed upwards but because resolution was so low it was easier to draw an arrow at a 45 degree angle.

The Role of Text in UX

As software and apps become more user-friendly and commonly-used icons become universally understood, there is a growing tendency to scrap text.

Microsoft experimented with the minimalist icons-over-text approach in their release of Outlook 1997. As you can see from the toolbar, they left out the text descriptions and as a result non-experienced Outlook users apparently stopped using the toolbar altogether:

2016-07-06 16_01_02-ToolbarCompare-11-1-2005.png (590×113)
Microsoft Outlook 1997
Several designs later, with Outlook 2000, they had a rethink and text was added back in:

2016-07-06 16_06_09-outlook01.gif (768×537)
Microsoft Outlook 2000
While more recent designs are less icon-assisted and text has even clearer prominence:

2016-07-06 16_09_20-Inbox - james.scott@hoistgroup.com - Outlook.jpg
Microsoft Outlook 2013

Digital designer Thomas Byttebier makes some excellent points about the importance of using text in his blog here, with the concluding statement being “when in doubt, the best icon is a text label.” He lists a number of extremely popular apps and sites where icons are pretty ambiguous. Take Instagram and Spotify for example. Are people aware of what this icon actually does?

2016-07-06 17_13_37-Start

2016-07-06 17_12_09-Spotify

In both cases this in-tray icon is for accessing your inbox and sending direct messages but I think the messaging feature is clearly overlooked in both applications. When I asked friends who have been using the applications for several years whether they were aware of the messaging feature they just looked at me blankly. One said “Oh, that bikini thing”, the other thought it was a basket. So there’s clearly a lack of clarity over the  purpose of the icon but whether that’s due to the ambiguous design or a lack of need, I’m not sure. It’s probably a bit of both.

Twitter have also had some issues with ambiguous and non-universal icons, often presuming that users will just intuitively understand what the icons do and sometimes getting it wrong. As a result Twitter’s user growth has actually slowed as new users that are attracted to the site often have a hard time catching on to how it works.

pict--iphone-screen-template---messages--messages---templatepict--iphone-screen-template---messages--messages---template2

The arrow icon for ‘Reply’, the envelope icon for ‘Message’ and the ellipsis (three dots) ‘More Options’ icon are recognisable but the heart icon for ‘Like’ will only be familiar with people who have used Instagram and other social media. A new user is unlikely to know what the ‘Retweet’ icon does unless they are familiar with Twitter’s basic concepts. It is interesting to note that Twitter have added text labels to the bottom five icons (highlighted in green in the image above) because other than perhaps ‘Messages’ their function is not obvious to the user.

While documentation is sometimes seen as an afterthought in the development process, in my opinion the text and written content is an inherent part of user experience for all software, no matter how intuitive the UI designer thinks his icons are or user-friendly the product is. If you want to avoid ambiguity, text will always be the best way to get the message across to the user.

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.

How to become a Technical Writer

If you’re an analytical journalist who is looking for a change, a budding writer with an interest in technology or an experienced programmer who is secretly an aspiring wordsmith, then technical writing might just be the answer for you.

What is a Technical Writer?

Technical writers or authors help to communicate technical information and instructions for products, such as software and hardware, in a way that is easy to understand. This can include writing user manuals, online help, release notes, integration guides, fact-sheets, wikis and APIs among others. Other methods of communicating information include producing video tutorials, graphics and illustrations. If you’ve ever read the mini instruction manual that came with your smartphone or clicked the ‘?’ icon or ‘Help’ button while using a piece of software then the content was probably written by a technical writer.

The role is sometimes given other names such as technical communicator, documenter, information designer and content strategist. Occasionally the content is written by developers or business analysts.

Moving from Journalism into Technical Writing

After nearly six years of writing for local newspapers and witnessing more and more job cuts as readership declined, I decided to jump ship and try something new.

Side profile of a journalist typing on a typewriter

My lifesaver came in the form of technical writing, and while it might not be for everybody, I knew straight away that it was the right move for me. Skills I had used for years such as interviewing, writing shorthand and producing accurate copy quickly proved to be very much transferable but instead of interviewing local politicians and press officers to write news stories, I was speaking with developers and testers to produce release notes and user instructions. Similarly, my multimedia skills and experience with Photoshop and video editing came in handy for creating graphics and video tutorials. It certainly helped that I’d always been interested in computers and had worked on blogs (so had some basic knowledge of HTML etc) but I found most aspects of the job just suited my existing skill set.

What Background should a Technical Writer have?

While I have encountered that some companies who would rather hire technical writers with a coding or technical background, I don’t think that should be a stumbling block if you’re interested in pursuing a career in technical writing. I have met technical writers who have previously worked in customer support, higher education and even photography. Although I have personally found my journalistic skills incredibly useful, I think as long as you are a good writer, are able to think analytically and are happy to constantly learn new things then a career in technical writing could be for you.

The sections below will provide tips and advice that will help you if you are considering pursuing a career in technical writing:

1. Qualifications

Some employers will look for a degree in computer science or similar but requirements can depend on the subject matter of what is being documented. Degrees in science, engineering and English are all suitable.

While there aren’t actually too many universities which offer accredited technical writing courses, it certainly wouldn’t hurt your CV to have some kind of formal training in technical communication. The University of Limerick offers a graduate certificate in technical communication (distance learning), while  other universities such Imperial College and Norwich offer more specific or specialists courses such as science communication and communication design.

Introductory and more advanced courses with accreditation by the Institute of Scientific and Technical Communicators (ISTC) are offered by Cherryleaf, Armada and ESTON.

2. Commonly Used Tools

Another key thing that most employers look for is experience with the required publishing tools that their documentation team use or have used. The table below lists many of the products and tools that are commonly used by technical writers, although there are many others:

word_2013  Microsoft Word  Word processing tool.
sharepoint2013  Microsoft SharePoint  Documentation management tool.
default-space-logo-256  Atlassian Confluence  Documentation management/ team collaboration.
icon-flareLargeBgColor  Madcap Flare Help authoring tool.
FM-icon  Adobe FrameMaker  Document processing tool.
2016-05-18 12_27_22-Films & TV  Adobe RoboHelp  Help authoring tool.
Adobe_Acrobat_DC_Icon  Adobe Acrobat  PDF reading and editing tool.
Notepad  Windows Notepad  Plain text editing tool.
notepadplusplus.6.9.1  Notepad + +  Text and source code editor for Windows.
Adobe_Photoshop_CS6_icon.svg  Adobe Photoshop  Image and photo editing software
Visio-icon  Microsoft Visio  Diagram and flow chart creation tool.
visual_studio_2012___windows_startscreen_icon_by_revisionzero-d5qnp17  Microsoft Visual Studio  Integrated development environment.
greenshot_0a  Greenshot  Screenshot capture and editing tool.
img_snagit-icon  Snagit (TechSmith)  Screenshot capture and editing tool.
icon128-2x  Camtasia (TechSmith)  Screen recording and video editing tool.
Adobe_Illustrator_Icon_CS6  Adobe Illustrator  Vector graphics creation tool.

If you haven’t used any of the software listed above, it is possible to download 30-day trials of some of these (Adobe Software especially) and either play around with them or watch some tutorial videos online and read online help to learn how they work. Many open source tools such as Greenshot and ScreenToGif, which can be used to create .gif files from screen recordings, are completely free to download and use.

Another useful tool to use when starting out as a technical writer is to buy a copy of the Microsoft Manual of Style. This is a great everyday generic style guide that can be used as a guideline for your own technical writing or as a template when creating a style guide for an employer.

3. Coding Skills

While it is not essential, as I said before, having some basic coding knowledge would be extremely beneficial if you are serious about becoming a technical writer. Some people recommend learning the basics of HTML, CSS and some XML at the very least.

coding-future

There are some excellent online resources where you can learn different coding languages. These include:

Codecademyhttps://www.codecademy.com/

Khan Academy – https://www.khanacademy.org/computing/computer-programming

Code School – https://www.codeschool.com/

W3Schools – http://www.w3schools.com/

There are more out there and there are also plenty of forums and tutorial videos available which should give you the basics. Starting a blog or creating a website online is also another great way to learn and develop your HTML skills at the very least.

4. Build a Portfolio

It’s difficult to build a portfolio when you are just starting out and do not have work experience but one option is to go to freelancing websites and find some documentation jobs, write submissions and use them for your portfolio, whether they get accepted or not. Another option is to find an open-source collaborative project such as Mozilla Firefox (and Thunderbird) where the documentation is written by volunteers. Click here for more information.

If all else fails then simply produce dummy documentation samples such as user guides or fact-sheets for existing products. It would be good to have half a dozen or so of different document types, preferably both user-facing and back-end, to really showcase your work.

5. Networking

Once you have the qualifications, knowledge of the tools and a small portfolio, it is important to network and develop contacts in the industry. It is a good idea to look up and contact firms which have existing documentation teams who might need a junior technical writer in the future.

networking

Alternatively, write a list of companies you’d like to work for and either check their career sections or email them speculatively offering your services. Other ways to build your reputation and network is to send your CV out to recruitment agencies who specialise in tech jobs, add contacts on Linkedin and attend technology job fairs in your local area to get your name out there.

Finally, good luck with your search!

Was this post helpful? Let me know if the comment section below.

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.

Gamification: Let the Games Begin!

Following the boom of video arcades and the emergence of home computers, many Millennials like myself were playing computer games not long after we could crawl. I remember playing games like Chuckie Egg on my dad’s ZX Spectrum from the age of  five or six and later a whole host of DOS games on floppy disk. This early exposure to technology and confidence that we can figure things out for ourselves has led to a certain amount of resistance to using help if we think we don’t need it.

Chuckie_Egg_Spectrum
ZX Spectrum classic game Chuckie Egg which was released in 1983.

Similarly, while my generation consider themselves tech-savvy, we aren’t a patch on our younger and counter-parts from Generation Z; the kids born with a smartphone in one hand and an iPads in the other. The bad news is this so-called iGeneration only has an 8-second attention span (at least according to market research) which makes them a slightly problematic audience. However, there is a perfect solution for appealing to the younger generations, the game-loving tech know-it-alls with short attention spans, and the answer is gamification (apologies to any haters of jargon if that word made you shudder!).

For those of you unfamiliar with the term, gamification essentially means adding the typical elements of game playing such a point scoring or a reward scheme to a non-gaming application (typically social media and e-learning sites but occasionally help service desk sites) to encourage user engagement. To be more scientific than that, researchers discovered that playing games and scoring points causes the human brain to release the neurotransmitter dopamine which in turn leads to brain stimulation reward (BSR). This is the phenomenon in which the regions of the brain are stimulated following a reward-based outcome such as eating food when the body is hungry or drinking when the body is thirsty. The same reward pathway has a key role in behaviour such as drug addiction where the person compulsively seeks the reward of using a particular drug. So in layman’s terms, gamification is a way of getting your users addicted to your application, whether that be an e-learning site or even a help system.

Gamification Examples

One of the best known examples of gamification is Tripadvisor where users are rewarded for engagement the marketing team. Travellers become hooked by the reward scheme, which sees posting reviews and photos rewarded in the form of points and badges. It’s clever really, Tripadvisor gain free content which boosts their revenue (which was $1.246 Billion in 2014!) by giving out points and badges that are about as much use as a chocolate teapot.

TripAdvisor-2
Evidence of an addict: Some of the author’s Tripadvisor badges.

As you can see from the screenshot above, I developed something of an unhealthy addiction to Tripadvisor myself. I receive emails prompting and encouraging me to post,

This slideshow requires JavaScript.

A great example of an e-learning app with gamification applied is Duolingo. The site was launched in 2011 by university computer science professor Luis von Ahn, who is also the creator of crowd-sourcing bot-tester CAPTCHA, and has grown exponentially to the extent that it now has 120 million users worldwide, with gamification being a large driving force behind its success. User engagement is predominantly led through rewards such “lingots”, given for completing a language lesson, that can be used as a form of virtual currency to buy power-ups, practice and bonus skills within the app:

Lingot1

Lingots

Users are also encouraged to take a lesson each day to continue their “day streak”, consecutive days in which they’ve used the app and gain experience or “xp”, which again is a common aspect of gaming; a character gains experience for time played and missions completed. When lessons are completed for a particular subject, it turns gold, which again is a form or reward, and when the user completes a level or language they also receive an award (as shown below):

14191829821_9b44315356_z (1)

Further user engagement is encouraged through a user forum called a discussion stream where users can post comments and earn up-votes in a similar format to Reddit. Interestingly, when a user posts, the languages they are studying in Duolingo, their level for each language and their day streak is also displayed alongside their name. This gives each user a certain status within Duolingo and encourages user participation by targeting the competitive nature of each user. E.g. By taking more lessons, they increase their status/stature in the user forum.

duo2

Duo1
Noob vs Pro: My profile above (beginner French & German, no streak) alongside a guy who is learning 19 languages including Welsh, Russian and Turkish as well as a 643-day streak. Woah!

Another example of gamification where users are rewarded for input and participation is the web’s largest programming community, Stack Overflow. Users receive different badges for posting questions and answers which fall into three categories: gold, silver and bronze depending on how well-received it is by other users.

2016-04-29 15_07_26-Badges - Stack Overflow

As a user acquires more badges, their reputation on the Stack Overflow also improves. The user profile below is the top-ranking programmer on the site, having provided an impressive 3,555 answers and reaching more than 600,000 people. This user’s ranking make him  more credible and trustworthy in the eyes of other users.

Stackoverflow.jpg

Skype, which I looked at it in my first help review blog, have used a similar but more basic gamification model in their Skype Community where users are encouraged to gain ‘Kudos’ and top the ‘Most helpful’ board:

2016-04-26 14_45_36-Skype Community

The most helpful and active Skype Community users are also recognised or rewarded by being made ‘community ambassadors’, denoted by the star shown next to “techfreak” in the screenshot above. As well as having status in the community, these ambassadors also get to attend monthly meetings withe a representative from Skype, again taking user interaction and engagement to another level.

Applying Gamification to Help

Although gamification clearly works for e-learning and other social media applications, in terms of driving user engagement it’s not so easy with help and documentation. Aside from the obvious cost implications involved with designing and developing your own points or rewards scheme or paying for an external gamification platform, it’s not particularly easy to apply it to standalone documentation. Yes, I suppose you could divide it up into sections or lessons with points or levels awarded for each completed but sometimes people only refer to documentation for one particular answer so I’m not convinced gamification is the answer here.

The best working model I have seen is in the examples above, in which user forums and communities are created and essentially crowd-source the answers to questions that might otherwise be covered by your documentation, help desk or support staff. That’s probably the best way forward in terms of encouraging users to interact with your documentation: run a user forum, encourage engagement through up-voting, offer good question and answer rewards, and promote user status or level upgrades to produce content that is time saving, good quality and most importantly, fun!