This is the third post in a month-long series centered around Sarah Maddox’s new book: Confluence, tech comm, chocolate: A wiki as platform extraordinaire for technical communication, published by XML Press.The book is choc-a-bloc full of tips from a technical communicator who has spent the last four years on Confluence. Learn how to harness the wiki’s social and collaborative features, turning technical documentation into true communication. Discover how technical communicators can drive the ongoing development of wiki technology. The blog series will give you a sample of some of the key themes from the book as well as provide you with some tips and tricks for using Confluence for technical documentation.

Let’s assume that your documentation wiki has taken its first steps. Content management is running smoothly. You’ve applied the guidelines from our previous post on managing updates by everyone, and your contributors are working together happily.

Now, how can you make your wiki fly?

Everyone knows the saying: A picture is worth a thousand words. Many people absorb information more quickly from a good image or diagram than from a block of text. But there’s more to it than that. Attractive and interesting pages attract people. By engaging our readers’ interest, we are making it easier for them to focus on and understand the information on the page. In other words, there’s more to it than pictures. Even if a good picture is worth 10 chocolates!

Visual, dynamic and real-time content

You can add images to a Confluence page, much as you’d expect in any other content development platform. You can also embed multimedia files that are hosted on the Confluence site. That’s neat. But there’s another area where the wiki shines: You can embed live content drawn from other sites.

Here’s an overview of the ways you can add visual and dynamic content to your documentation:

What about real-time content? Your page can display information live from other sites. When people open the page, they will see the latest information published from the source site:

Technical communication teams can take advantage of this real-time display of externally-provided information. Let’s say the marketing team has made a great video about getting started with your product. Or a community author has posted a presentation on SlideShare. You can tap into resources that are already out there. At the same time you are giving our readers great information.

Image is copyright © Ryan Maddox, 2012

Twitter plus wiki, the shiniest integration of all

People can put a world of meaning into 140 characters. For many people, Twitter is the first choice for sharing information. They send and read Tweets on the web, on their phones, on Facebook, via email, RSS, desktop apps… Anywhere, anytime.

Wouldn’t it be cool if you could Tweet technical information to those people! Even better, imagine using Twitter to draw people into the documentation. We’ve experimented with ways of doing both those things!

Inviting and publishing tips via Twitter

We encourage customers to Tweet their hints and tips about a product. Using a special hash tag, people share their knowledge with us and other customers. What’s more, we publish the Tweets live in the documentation. Click the Jira or Confluence badge to see “Tips via Twitter” in action!


Interactivity and games in documentation

Here’s an interesting thought: technical documentation can benefit from a laugh and a game. We’ve put the idea into practice in our Dragon Slayer documentation. This is a configuration guide tricked out as a game, with Twitter as the tool that the participants use to communicate. Installing and configuring the full suite of Atlassian applications takes a bit of time and can be a daunting experience. So we’ve created Sir Charlie of Atlassian to lead you, the fearless dragon slayer, through the steps. At the end of each stage, you can Tweet your status and check the Twitter stream to see how others are faring.

Fare ye well, brave souls and true. I’m starting the Atlassian Dragon Quest!

Twitter as a medium for release notes

We Tweet the highlights of our major releases, using Twitter’s hash tags to connect the Tweets. People share the Tweets, reply to them, and click through to see the full release notes. Sarah’s book gives all the details about this technique and the other ideas in this post, as well as the lessons we have learned from each experiment.

Live Webinar: Confluence as a Platform for Technical Documentation

Thursday April 12th, 2012 | 8:00 AM PST

Join Atlassian technical writer Sarah Maddox, as she shows how she used Confluence to author her book and shares how you can customize Confluence to fit your technical documentation requirements. Special guests from Stepstone Technologies and k15t Software will demonstrate how their add-ons make it easy to brand your online documentation and facilitate the entire documentation lifecyle  with Confluence.

Register now for your chance to win one of 10 copies of Sarah’s new book, a Zen Foundation license valued up to $12,000, or one of k15t’s Scroll Wiki Exporters valued up to $3,600.

Stay tuned

Having fun yet? We will continue to celebrate the art of technical writing, Sarah’s new book, and the use of Confluence next week with a post dedicated to providing you with helpful tips and tidbits for developing the best technical documentation possible.

Buy the book

Sarah’s book gives all the details about techniques for making your documentation interactive and engaging  and goes into greater detail on the other ideas mentioned in this post, as well as the lessons we have learned from each experiment. Buy Sarah’s book Confluence, tech comm, chocolate: A wiki as platform extraordinaire for technical communication today to learn more!

Try Confluence today

Give your technical documentation a boost with Confluence. Start a free 30-day trial and see how easy it is to start developing your technical documentation. With licenses starting at $10 for 10 user, OnDemand or Download, you can’t go wrong.


Turning Documentation into Communication with Conf...