AODC day 3 – Delivering documentation on a wiki

This week I attended the 2009 Australasian Online Documentation and Content conference (AODC) in Melbourne. On Friday, the third day of the conference, it was my turn to give a presentation.

My AODC presentation was about using a wiki for technical documentation. Here are the slides and supplementary material from my presentation:

I hope the slides with additional notes will be useful to the conference attendees, and maybe also to people who couldn’t make it to the conference this year.

Update November 2009: I wrote an article based on the presentation, which appears in the October 2009 edition of Southern Communicator. A PDF extract is available for download from this blog post.

Background to the presentation

Writing technical documentation on a wiki is what I do all day and what I’ve been doing for almost two years now. I’ve been a technical writer for more than ten years, using various tools and working in various businesses. I’ve enjoyed every authoring tool I’ve used, and wikis are no exception. There are difficult bits, of course. But there’s that satisfaction you get when you see your document displayed in an aesthetically pleasing and functionally useful way. Wikis do it differently, but the sense of delight is the same.

I’m a technical writer at Atlassian. We use Confluence wiki more or less “out of the box” to author, manage and publish our documentation. We don’t extend the wiki’s core functionality via plugins or other customisations (with a few exceptions). There are two reasons for this decision:

  • Atlassian follows the principle of “eating your own dogfood”. That means that you use your own products, so that you can feel your customers’ pain. And their pleasure 🙂
  • We make our documentation available as an XML download, so that other people can upload it as a wiki space on their own Confluence instances. If we used a number of plugins that are not a standard part of Confluence, then other people would not be able to use the documentation in this way unless they installed the same plugins.

So my presentation was about the features of the wiki that are especially useful in technical documentation, and the procedures you might put in place to work around the bits that the wiki doesn’t do for you. The main points I discussed are:

  • How a wiki is useful in agile development.
  • Workflow and tracking.
  • How to put some structure into wiki documentation.
  • Release management.
  • Steering wiki development — how we as technical writers can let wiki developers and plugin developers know what features we’d like in a wiki.

The content is similar to the talk I gave at WritersUA in Seattle, except that the AODC presentation was double the length (an hour instead of half an hour). So I was able to add some extra information and do more live demonstrations.

Breaking news not included in the notes

The presentation mentions the Scroll Wiki Exporter, that converts wiki markup to DocBook. In the last week K15t Software have released version 1.0 of Scroll, their first production release. See the Scroll web site and my blog post.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 23 May 2009, in AODC, atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , . Bookmark the permalink. Leave a comment.

Leave a Reply

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

You are commenting using your 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: