Social media in technical documentation – a presentation

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:

Social media in technical documentation - a presentation

Social media in technical documentation - a presentation

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
  • Twitter
  • Flickr
  • Wufoo

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.

Craig Smith snapped a cool picture of me giving the presentation. He also wrote some great summaries in his Atlassian Summit 2010 Day 1 Wrapup.ย  Thanks Craig!

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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 19 June 2010, in atlassian, Confluence, technical writing, wiki and tagged , , , , , , , , , , , , , , , , , . Bookmark the permalink. 7 Comments.

  1. Hi Sarah,

    You did a great job with your presentation “Felt the Earth Move When I Read Your Docs”. You shared many good ideas, tips and tricks to make documentation more engaging and even fun for the reader.

    I’ve been experimenting lately with screen- and slide-casting as a means to make documentation and web-based articles that I author more meaningful and engaging for users.

    Foir example, have a look at the current JIRA article “Visual Workflow Specification Speeds JIRA Application Development” on my blog (

    After I wrote this article, I decided to link the post thumbnail image to a screencast that explains more of the article’s content. I’ve found I can explain a concept more quickly and effectively via a screencast, saving pages of written text that many people will rather watch than read.

    Screencasts are certainly not new to Atlassian. Maybe future documents and Wiki’s can also link to screencasts as well?

    Take care and thanks for posting the video and slides of your presentation.

    • Hallo Jim

      Thank you for your kind comments! I think your idea of screencasts is a great way of engaging readers. In particular, people are different and we all absorb information and learn differently. For many people it’s much easier to absorb information via a diagram, and even more so when someone is explaining the diagram to them, as in the screencast you linked from your post. Really great work.

      One problem with videos and screencasts is that they take more time and effort to maintain, as a product moves through various releases and the user interface and features change. I guess we could get around that by choosing carefully which aspects of a product we document using these media types. For example, your workflow diagram is one that will remain valid because it illustrates a core concept rather than the UI or something that may change.

      Thanks for the cool addition to this discussion!

  2. Question.. anybody knows how to get your market from twitter???

  1. Pingback: Technical writer’s pick of presentations from Atlassian Summit 2010 « ffeathers — a technical writer’s blog

  2. Pingback: One of the most dreaded tasks – writing documentations « Akeles Consulting

  3. Pingback: Notes from “How Social Media Is Changing Communications” presentation to The Society for Technical Communication | Carr Communications Inc.

  4. Pingback: Rewriting the rules for TRIRIGA docs |

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: