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:
- Video and audio. Display multimedia files attached to Confluence pages, or embed videos from YouTube, Dailymotion, Vimeo, and more – now easier than ever with autoconvert.
- Pictures and diagrams. Display your screenshots and other images on pages. Embed slide shows from Flickr. Create diagrams using Gliffy, Creately or other Confluence add-ons.
- Presentations and other documents. PowerPoint presentations, Microsoft Office documents, PDF files, and presentations hosted on SlideShare, SlideRocket, Scribd, and Google Docs – see what else you can do with the Widget macro.
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:
- Gadgets. Add an iGoogle gadget to your wiki page. Use a Jira gadget to display information about your projects and issues. Or show content from Confluence on another site, using a Confluence gadget.
- Issue trackers. Enrich your release notes with the Jira Issues macro to draw a filtered stream of items from the issue tracker.
- Other integration points. Activity streams, news and blog posts, micro blogging, calendars… people are developing more integrations as you read this post.
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.
