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 (Twitter.com).
    • 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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 18 March 2011, in atlassian, Confluence, technical writing, wiki, WritersUA and tagged , , , , , , , , , , , , , , , , , , , , . Bookmark the permalink. 16 Comments.

  1. Hi Sarah,

    I watched your demo of your project at the WritersUA Peer Showcase. I’m glad you won the award–I thought that marrying wiki documentation with a Twitter feed is a great idea!


    • Hallo Robert

      Thank you so much! I didn’t get to see your WritersUA talk on web analytics, which is a great pity. I would love to hear it. Are you planning to blog about your presentation? If you do, I’ll definitely drop by and have a read. 🙂

      Thanks also for blogging about mine. At the moment, I’m getting some odd visual results on your blog (using Firefox). I’ll try again later!


    • Update: Robert, your blog looks great in IE. Maybe it’s a Firefox-specific problem? It’s a great-looking blog. 🙂
      Cheers, Sarah

  2. I attended your presentation at WritersUA and was thrilled to know that you’re doing what I’ve been trying to convince companies that they should be doing. Your success is a fantastic case study which proves that using social media can and is successful.

    • Hallo Pam,
      Thank you so much, that’s praise indeed! I missed both your sessions, which is a great pity. I think we should persuade Joe to stretch the conference out longer with fewer sessions per time slot. Or we should learn to session-hop! What a great conference it was. :
      Cheers, Sarah

  3. Congratulations on your award, I’m happy for you! Your presentation was very useful and very relevant to my situation. And reading your blog posts was *almost* like being at the conference in person!

    • Hallo Davide
      Thank you so much! It’s great that my presentation is relevant to you at the moment. Let us know how everything goes and whether you get a lot of support from your colleagues. I’m in such a lucky situation, where we’re encouraged to experiment with techniques and tools!

  4. Congratulations, Sarah! I’m thrilled! You’re always breaking new ground with use of social media. It’s been great watching this journey of yours over the past year or so. You’re really paving the way. I’m so glad to see you get the recognition you deserve. Yea!

  5. Hallo all

    Update on how to create an auto-tweeting link:

    The Twitter API has changed, meaning that we need to change the URL that we use for auto-tweeting links. The changes seem to require the following:
    1) Remove the word “home” from the URL. Instead of this:
    “http://twitter.com/home?status=My status”
    It’s now this:
    “http://twitter.com/?status=My status”
    2) If you URL-encoded your message, then you need to get rid of all the plus signs but leave the special characters encoded. So, instead of this:
    You’d now have this:
    “My status encoded %23techcomm”

    Here’s a full example of something that works. Let’s say you want to tweet “My status encoded #techcomm”. This is your URL:
    “http://twitter.com/?status=My status encoded %23techcomm”

    Cheers, Sarah

  1. Pingback: WritersUA 2011 – Out of box experiences to delight your customers « ffeathers — a technical writer’s blog

  2. Pingback: WritersUA 2011 wrapup – a great technical communication conference « ffeathers — a technical writer’s blog

  3. Pingback: Using social networking for documentation « TACTICS Blogs Information Mapping

  4. Pingback: Case Study: How a Silent Movie Told the Best Story « Freelance Technical Writing Services | Web Writing Services

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: