AODC 2010 day 2: Engaging your readers in the documentation

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.

AODC 2010 day 2: Engaging your readers in the 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. 🙂