Blog Archives

WritersUA 2011 – Using social media to get readers involved

This week I attended the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Tuesday it was my turn to present a session, called “Getting your readers involved in the documentation”. This post summarises my talk and offers you the opportunity to download the presentation in PDF form.

At Atlassian, we’ve been using social media in various ways, to make our documentation a living, interactive hub where people can find the answers to their questions, talk to us, talk to each other, and use the documentation as a tool to help each other.

Download the presentation

If you like, you can download a copy of my presentation in PDF form. I’ve put a lot of information and references into the speaker’s notes too.

What’s in this post

The rest of this post is a summary of and discussion of my presentation, and of the condensed version that I showed people at the WritersUA peer showcase.

The social organisation

We know that organisations are becoming more social. Studies show that engaged customers buy more, are more likely to be satisfied with the product, and are more likely to help each other use the product.

In the same way, I’d like to propose that engaged readers will keep coming back to the documentation, are more likely to be happy with the documentation, and will use the docs as a tool to help each other.

The tools

The tools and ideas I discussed are:

  • Using a wiki as the documentation authoring and publishing tool – Confluence. In our documentation and in my presentation I’m using Confluence wiki. But most of the tools and ideas are transferable to online documentation on any platform.
    • Allowing readers to add comments to the documentation pages.
    • Allowing various groups of people to edit your documentation, including community authors, all the company staff, customers, the whole wide world.
    • Using wiki permissions to determine who can do what.
    • Monitoring the updates via RSS feeds and wiki watches.
  • Designing a contributor licence agreement, based on the Apache Contributor License Agreement, to protect the rights of all parties.
  • Adding a Creative Commons copyright licence to the documentation pages. Ours is a Creative Commons by Attribution licence, which means that anyone can use the documentation for any purpose they like, provided they acknowledge us as the source.
  • Using a web service that allows you to design an online feedback form, then grab the HTML to embed the form into your own documentation page – Wufoo. When people fill in information on your form, the data goes into the Wufoo database. You can then log in to Wufoo and see the results, get some statistics, and so on.
  • Linking to blog posts written by community developers and authors from within your documentation. For example, the JIRA Tips of the Trade, the Crowd Tips of the Trade and the Confluence Tips of the Trade.
  • Encouraging people to interact with your documentation via Twitter (
    • Using Twitter as a medium for your release notes.
    • Encouraging people to tweet hints and tips about your products, and then taking it a step further and embedding a live stream of tweets on a documentation page. See the JIRA Tips via Twitter and the Confluence Tips via Twitter pages.
  • Rewarding contributors by giving them an online badge that they can add to their blogs or other social sites.
  • Organising a doc sprint. This is an event, similar to the book sprints of the opensource world, where a group of people get together for a specific period of time to write a specific set of documentation. We have held two doc sprints, with participants working in our offices and remotely all over the world. We plan to hold more.
  • Bringing back fond memories of a documentation-related event, and encouraging people to join in next time, by streaming photos of the event onto your documentation page directly from Flickr. Flickr is a web service where you can upload and share photographs with your community, friends and the world.
  • Building fun, a game, a challenge and interactivity into your documentation. I demonstrated at the Dragon Slayer documentation.

The Dragon Slayer Documentation

The Dragon Slayer documentation is a set of installation instructions that we created to solve a specific problem. Atlassian, the company I work for, has a great set of products that you can set up to work together as an integrated development suite. At the moment, though, the integration process is long and complex. In fact, it’s painful. The products were not originally created to work together, and we’re developing the integration incrementally. The setup process is getting easier all the time, because our developers are working to improve the process.

In the meantime, we needed some documentation that leads people through the setup process, to create a specific environment with some good simple examples of the integration possibilities. This documentation does not replace the existing installation and upgrade guides for each product. Instead, it’s an additional tool to get people started quickly when they want to set up the full suite of products.

What’s more, because the process is long and complex, we wanted to turn the pain into fun. So we challenge people to come a slay the dragon. The dragon is, of course, the setup process.

A summary of the Dragon Slayer docs:

  • There are 9 stages, corresponding to 9 pages. Each stage consists of many steps.
  • We’ve taken pains sure ensure that the fun stuff is at the top and bottom of the pages. In between is good, solid technical writing – “how to” steps that we test rigorously, end-to-end, before making any updates, to ensure that the entire environment will work.
  • There’s a pretty picture and some funny words (shamelessly cribbed from various online translations of Dante) at the top of each page.
  • At the bottom of each page, we congratulate you on your victory and tell you what you have achieved so far.
  • When you start out on the dragon quest, you meet Sir Charlie of Atlassian, whom you will recognise as the dude in the Atlassian logo. He is scantily clad and has only a staff to ward off the dragon.
  • As you go through the stages, Charlie acquires armour and a sword, so that he is well equipped by the time he meets the dragon in stage 9.
  • When you finish the dragon quest, you get a T-shirt. (A real one.)
  • During the quest, you can intereact with other dragon slayers via Twitter. We’ve crafted some funny tweets that are a call to action. If you click the “Tweet” link, we prepopulate your tweet box with those words. You can delete or change them before tweeting. We also embed a live stream of tweets on the Dragon Slayer front page, so that people can see which dragon slayers are out there right now.
  • Each page also has a number of links to the dragon slayers’ forum, where you can discuss any problems you encounter and swap ideas with other people going through the procedures at the same time as you.

The plan is that the Dragon Slayer documentation will morph into a set of quick, simple steps. The dragon may disappear entirely. Or maybe not. Watch this space. 😉

The WritersUA peer showcase

I presented a condensed version of the presentation at the WritersUA peer showcase on the last day of the conference. What happens at the peer showcase is that you sit at a table for two hours, and people drop by in groups or individually to see your project. So you need just a short demonstration. I focused on our use of Twitter in and around the documentation, and specifically on the Dragon Slayer documentation.

I was completely overjoyed when I won the award for the most innovative peer showcase project at the 2011 Conference for Software UA. Thank you so much to everyone who voted for our project, and to Atlassian for giving the technical writers the opportunity to do such fun stuff in our documentation.

WritersUA Peer Showcase trophy


I hope you find the attached presentation useful. Let me know what you think, and if you’re doing something similar.

Chocolate, dragons, technical writers and team spirit

A few days ago, our technical writing team went on a chocolate outing. This is not a rare occurrence. 🙂 This time I have some pictures and a few musings about the confluence of teams and chocolate.


Chocolate, dragons and technical writers


Chocolate, dragons and technical writers


Chocolate, dragons and technical writers

We decided that was one user guide we could all follow without difficulty!


For me, one of the most important aspects of my job is the team I work with. After all, I spend most of my waking life with them. It’s good to build up some common interests, other than the work itself, so that you have something to talk about, something to bind you together, even something to complain about.

I think fun is very important. But “fun” is a fuzzy concept. People have different ideas of what constitutes fun and technical writing teams typically consist of very disparate individuals. So how on earth do you find something that everyone will consider fun, interesting and invigorating?

Funnily enough (heh), we’ve found that it just happens. We have a great bunch of people in our team. Every one of us wants everyone else to feel good in the team. So when a possible “common interest” arises, everyone buys into it.


Earlier I wrote that it’s even good to have something to complain about together. Don’t we all love to exclaim in anguished tones, and isn’t it a good thing if the object of such gleeful anguish is not our job! I have a Calvin and Hobbes cartoon above my desk at work, showing Calvin’s father with a mangled bicycle, obviously the result of a bad stack. The caption reads something like:

“The secret to enjoying your job is to have a hobby that is even worse.”

Our technical writing team is keen on rollerblading. Actually, we’ve only done it once, but we plan to get out there again soon. And being keen doesn’t mean we do it well, just that we’re happy to give it a go. Or simply to watch our team mates fall off the blades! We made it into the Cherryleaf I’m a technical writer and I’m not boring annals.

But can you guess what the most popular common interest is? You got it: chocolate. And it’s not something we complain about!


We’ve taken to “rewarding” other people, those who are not fortunate enough to be technical writers, when they do something that improves the documentation. How do we reward them? With chocolate of course.

Our latest reward went to Jens, who is doing some awesome work on a “documentation” theme for Confluence wiki. (Yes, it’s true! I’ll let you know more about it when there’s a prototype ready for trial.)

We went to at Max Brenner in George Street, Sydney. Clockwise from the left, here are Rosie, Jens, Ed, Giles and Andrew (I was taking the photo):

Chocolate, dragons and technical writers

Chocolate, dragons and technical writers

Lucky Jens!


Another thing we do to engender team spirit is to dress alike. 😉

Heh, just kidding. But on this occasion, we all made sure that we wore our new Atlassian Dragon Quest T-shirts.

Warning! The shirts are very green. When we all appeared together, an involuntary gasp of horror escaped Penny, one of our QA engineers:

“My eyes, my eyes.”

So here we are, the Atlassian technical writers on a chocolate outing in our Dragon Quest T-shirts. Clockwise from the left — Ed, Giles, Andrew, Rosie and Sarah:

Chocolate, dragons and technical writers
Chocolate, dragons and technical writers

I count myself extremely lucky to be part of such a great team! Do you have any stories about what your team gets up to?

I got dragons and tweets in my documents

You may think you have problems, with the odd misplaced apostrophe or errant semi-colon in your documents. Well, there are dragons prowling around mine, and tweeting dragon slayers too!

A few weeks ago some smart Atlassians had the idea of making it feel like fun to set up a number of our applications as an integrated Atlassian suite. (I work at Atlassian, makers of Confluence wiki, JIRA bug tracker, and other applications for software developers.)

We’ve known for a while that it’s, uh, difficult to integrate our apps. In fact, people have used somewhat stronger words to describe the process. The problem is that the applications were developed separately, and not originally intended to talk to each other. But now we’re working towards providing an integrated platform. So, a group of Atlassians mused, why don’t we turn the setup task into a challenge and offer our doughty customers and other brave souls a reward when they get to the end?

And so the “Here Be Dragons” project was born. At heart it’s a set of documents that leads people, or “dragon slayers”, through the process of integrating six Atlassian applications. It’s also a quest, where the hero acquires better armour and more strength as he passes each of the eight stages. And behind the scenes it’s serious stuff, because it’s given us a good idea of exactly what we need to improve to make the integration process painless.

The documentation

We needed a stalwart set of documents to lead people through a typical installation and integration process, with detailed step-by-step instructions and even exact values to put into each configuration field. The idea is that people can set up their suite and get it working on the basic configuration, and tailor it later to their specific needs. I was the lucky technical writer given the job of writing the documents. It’s been a lot of fun, a lot of hard work, and one of the most unusual documentation jobs I’ve ever done.

It was a collaborative effort, with me writing the documents, testing each step in Windows as I went along and making deductions about the UNIX steps. Other people moved in to test the UNIX side of things. Jason from our Design team did the awesome art work for the documents and the T-shirt. Yes, of course there’s a T-shirt! Other technical writers, QA people and product managers contributed their knowledge of specific applications. Now Charlie the Dragon Slayer lives and breathes. (“Charlie” is the affectionate name given to the dude in the Atlassian logo. He also plays a major part in the Dragons documents.)

Twitter integration in the documents

I also added Twitter to the mix. Each page of the “Here Be Dragons” document offers our dragon slayers the chance to tweet their status, and pre-populates the tweets with suggested words. It was great fun composing the tweets and it’s even more fun now, watching the tweets pop up in the Twitter stream.

On Thursday morning a few brave souls and true had already started out on their dragon quest:

I got dragons in my documents

I got dragons and tweets in my documents

Pre-populating Twitter tweets

You can set up a hyperlink for people to click, that will open Twitter in their web browser and put some words into their Twitter message. If they haven’t yet logged in, Twitter will prompt them to log in. They can choose to edit the words, or just leave them as they are. They then send the tweet by clicking the Twitter “Update” button as usual.

All you need to do is add an HTML link pointing to the person’s Twitter “home” page and specifying a “status” parameter in the URL. Something like this:

<a href=” World”>Say hallo to the twittersphere</a>.

Here it is as a link:

Say hallo to the twittersphere.

If your message includes funny characters like a # sign, then you will need to URL-encode the message. For example, if you wanted to pre-populate a tweet with “Hallo World #testing” you would use this:

<a href=””>Say hallo to the twittersphere</a>.

Here’s a web site that will URL-encode your text for you.

Is “Here Be Dragons” really technical documentation?

Yes it is. The quest, tweets and pretty pictures happen around the edges. The central part of each document is hard-core technical how-to. 🙂

Scott Nesbitt has written an interesting post on the DMN blog about making user documentation more usable and user friendly. A dragon quest is a bit extreme, and it’s not something you get the opportunity to do often. But I agree with Scott that there’s a place for a lighter touch in much of the online documentation we write. It’s a delicate balance. On the one hand, it’s important that the writing style does not annoy or offend the reader and does not detract from the content. We also need to be aware of people whose first language is not the one we’re writing in. On the other hand, the occasional touch of humour or personality can focus the reader’s attention onto the page.

Dragons was a fun project. My other technical documentation assignments will seem a bit tame for a while. 😉

The URLEncode and URLDecode Page

%d bloggers like this: