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.
- Download the slides in PDF form (1,642 KB): Getting your Readers Involved in the Documentation (slides only)
- Download the slides with notes in PDF form (1,196 KB): Getting your Readers Involved in the Documentation (slides with notes)
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 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).
- 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.
I hope you find the attached presentation useful. Let me know what you think, and if you’re doing something similar.
Tags: atlassian, Confluence, doc sprint, Dragon Slayer documentation, dragons, engaging readers, games in documentation, humor, humour, social media, technical communication, technical documentation, technical writing, tips via Twitter, Twitter, Twitter and technical documentation, Twitter as a medium for release notes, user assistance, wiki, WritersUA, WuFoo
Last week I attended Atlassian Summit 2010. This was a conference in San Francisco focusing on Atlassian products such as Confluence wiki, JIRA issue tracker and more. At Summit, I presented a session on using social media in technical documentation. We also got a bit emotional about the docs. 😉
This was pretty cool. It’s the first time I’ve given a talk at an Atlassian conference. I was totally stoked and very nervous. Apart from a technical glitch or two (basically, Twitter was borked and my presentation was supposed to use Twitter) all went well. The audience was great. Thank you guys!
Downloading the presentation and watching the video
If you like, you can watch the video of me doing the talk (yes, they filmed me!) or download the slides:
- Watch the video of me giving the presentation on the Atlassian Summit 2010 site. You’ll see two big picture boxes in the right-hand half of the screen. The top one is the video. The first 22 minutes are my part of the session. In the second half of the video, Jeremy Largman talks about using Confluence as a support knowledge base and the tools the support team have built to extend Confluence. His presentation is awesome and packed with information. Well worth a watch. If you’d like to bump up our ratings, click the “Like” button just above the video. Let me know what you think of it too. I’m quite pleased with the way it turned out. I was expecting far worse! I was quite nervous, and my mouth got very dry. They’ve done a really great job of compiling the video with me and the presentation slides in one single view.
- See the slides on Slideshare: Felt the earth move when I read your docs (Slideshare)
- Download the slides in PDF form (1,901 KB) from this blog post that you’re reading now: Felt the earth move when I read your docs (slides only)
- Download the slides with notes in PDF form (1,907 KB) from this blog post: Felt the earth move when I read your docs (slides with notes)
Summary of the presentation
My talk was called “Felt the earth move when I read your docs“. Actually, it was originally called “Felt the earth move when I read your docs, mate” but someone with a fair bit of influence 😉 suggested that I remove the word “mate” from the title. You may notice that the word sneaked into the presentation itself anyway! Here’s a still image that I grabbed from the video:
It’s all about using social media to engage readers in the documentation. It’s also about fun and games and a bit of emotion in the docs. We looked at these tools:
- Confluence wiki
And we saw how we can use them in technical documentation:
- Using comments and forms to get actionable feedback from readers and customers.
- Linking to external blogs from within the documentation.
- How you can set up and manage your documentation while allowing external people to edit it.
- Using Twitter as a medium for release notes.
- Encouraging customers and readers to tweet hints and tips, and publishing the Twitter stream in your documentation.
- Holding a doc sprint.
To round it off, we looked at the Atlassian Dragon Slayer documentation, which combines a game, social interaction and a laugh with good solid well-tested technical writing.
The Atlassian Summit presentation is related to one I gave at AODC recently. If you’re interested in a lot more detail about each of the topics covered here, then take a look at my earlier post: AODC 2010 day 2: Engaging your readers in the documentation.
At the end of my slides are a number of references and links that I hope you’ll find useful. They include links to blog posts by other technical writers who are experimenting with social media and other adventures in the docs.
The Atlassian web site has a lot more Summit presentations, including a number about Confluence and how people are using it.
Attending this conference was a great experience. I’m really lucky to have had the chance to be there and to meet all those great people. Thank you to all the attendees for the ideas you brought and the fun we had.
Tags: atlassian, Atlassian Summit, Confluence, documentation as emotional experience, Flickr, games in documentation, humor, humour, social media, summit10, technical documentation, technical writer, technical writing, Twitter, user assistance, wiki, wikis, WuFoo
Last month I attended AODC 2010, the Australasian Online Documentation and Content conference. Over the last few weeks I’ve been posting my summaries of the conference sessions. Now it’s the turn of my own presentation.
My presentation was called “Engaging your readers in the documentation”. Conversation, the social web, community – they’re all the buzz. OK, sounds good, but how do you get your readers involved in the documentation?
Downloading the presentation
Attached to this blog post are two PDF files containing my presentation:
- Engaging your readers in the documentation: slides only – presentation slides only (2,327 KB).
- Engaging your readers in the documentation – slides and notes – slides with speaker’s notes (2,441 KB).
Overview of the presentation
At Atlassian, we’ve been experimenting with social media and other techniques. My presentation takes an in-depth look at the tools and techniques we’re using.
We write and publish our documentation on Confluence wiki. The wiki, and in particular a Confluence macro called the Widget Connector, provide many opportunities for integrating other social media into the documentation pages. Examples of such social tools are Twitter, Flickr and Wufoo.
Even if you’re not using a wiki, you’ll still be able to apply these ideas and techniques in and around your technical documentation.
The presentation covers the following techniques and tools for engaging your readers:
- Getting feedback from readers via comments on the documentation pages.
- Using Wufoo forms as another feedback mechanism. You can embed a Wufoo form into your wiki page or other web pages.
- Holding a doc sprint, where a group of people got together to write tutorials. Our focus was plugin and gadget development, so we invited the developers too. We use a Flickr photo stream in the doc sprint wiki to show the sprinters in action.
- A few ways of using Twitter‘s hash tags, viral tendencies and 140-character limitation to their best advantage. We tweet our release notes. In one of our long procedural documents, readers can tweet when they hit each milestone and can follow the tweets to see how others are faring. Breaking news: We’re about to start encouraging people to tweet their hints and tips. We’ll embed the Twitter stream into a documentation page, so that tweeters can see their tips appearing in our documentation, and readers can see other people’s hints in real time.
- Linking to external blog posts from within your documentation. Our “Tips of the Trade” pages link to external blog posts where our readers share their own hard-won tips and techniques.
- Letting other people edit your documentation. Is it safe? We use wiki permissions to control who can do what. Technical writers monitor all updates via RSS feeds and wiki watches. Our developer documentation is open for editing by any logged-in user. That means that anyone can click the “Sign Up” button, get a wiki user ID and start editing the developer docs immediately. We have a contributor’s licence agreement that we ask people to sign before they get permission to update the product documentation. A Creative Commons (cc-by) licence lets readers and contributors know what copyright rules apply.
- The idea of documentation as an emotional experience and of having a game in and around the edges of your documents. The presentation looks at a case study, Atlassian’s Here Be Dragons documentation.
- Lots and lots of links and references in the last few slides. In particular, I’ve linked to some blog posts by other technical writers who are talking about and experimenting with similar techniques. Anne Gentle’s book is a great source of ideas: Conversation and Community: The Social Web for Documentation. Peg Mulligan wrote about “social business, also known as enterprise 2.0″. Julie Stickler blogged on HeraTech about Agile Doc Reviews – The Documentation Sprint. Lisa Dyer writes “I suppose we’ll soon agree on a name for the era we’ve entered” in her blog post about “Business intelligence, intelligent content and devices, games, and noise”. Bill Kerschbaum asks “Did you hear the one about the user guide with a sense of humor?” Ellis Pratt’s writes on the Cherryleaf blog about “Turning technical documentation into an emotional experience (for the customer)”.
I hope you enjoy the presentation. Let me know if it gives you some useful hints and ideas. 🙂