Engaging readers in documentation

At the AODC 2010 conference, Sarah Maddox, who works for Atlassian, an agile development environment, spoke on engaging readers in the documentation and the concept of documentation as an emotional experience.

Sarah explained the advantages to both the customers and the company of involving readers (users) and discussed some of the techniques that Atlassian has been experimenting with. These include social media (blogs, a forum, and Twitter), a “doc sprint” (an intensive time spent producing documents such as tutorials), encouraging users to update community documentation on a wiki, links to readers’ blogs, and an interactive game that customers can use to help them through the complex installation and configuration of a product.

Anyone who has worked in both a traditional “waterfall” development environment and an agile environment, knows how different they are. If you are comfortable working in one, you may be quite uncomfortable in the other… or you may not, depending on your adaptabiity and tolerance for change. Personally, I thrive on change (or at least variety).

During my time at IBM, I worked on “waterfall” projects, which I found a bit stifling. Now I work with OpenOffice.org, which may or may not be “agile” but certainly is fast-paced in terms of iterative changes to the software. The user documentation team as a group (all volunteers) is always lagging behind the software developers. I suspect a lot of that time lag has to do with our failure to develop processes to handle the workflow, so I’m looking for ways to improve that workflow. Other problems are a lack of enough writers compared to reviewers and editors, and a constanting changing set of volunteers. Engaging volunteers isn’t all that different to engaging readers, and both could help with keeping the documentation up to date and relevant to the users’ needs.

I recommend Sarah Maddox’s blog. Her posts about AODC start here.


  1. Hallo Jean
    It was great meeting you at AODC this year. Thanks so much for linking to my blog. Now I’ve added yours to my feed reader to. I love finding more tech writing blogs, and especially those of people I know. Hope to meet up with you again some time!
    Cheers, Sarah

Comments have been disabled.