This is the last 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.
The wiki world is one of innovation and ideas. People dream, then build their dreams. Technical communicators, too. Confluence is a platform extraordinaire for technical communication, but it’s not perfect yet. We can help to make it so. The wiki is extensible. That’s what makes it a platform to dream of.
This post contains material from Sarah’s book, reproduced with her permission.
Image is copyright © Ryan Maddox, 2012
Two examples of wiki innovation
Let’s see what people are doing in the wiki world right now. Here are two of the innovative wiki developments Sarah discusses in her book: federated wikis, and a wiki on a stick.
Federated wikis
Ward Cunningham is the man who invented the world’s first wiki, WikiWikiWeb. Now he is working on an intriguing new project, a federated wiki. This is not related to Confluence specifically, but is an example of ongoing innovation in the wiki arena.
The idea of a federated wiki has been around a while. The aim is to link wikis together into a distributed network of wiki servers. People should be able to move from page to page in search of information, not really caring which wiki hosts each page. Ward describes his new project as the “smallest federated wiki“. One way it could be used is to share content across wikis! At the moment, the content in one wiki is more or less shielded from the rest of the world. You can export and import content, but there is no feature specifically designed to share content across wiki repositories.
Compare this to the source repositories that developers use. Developers can take a copy of a project (“fork” the project) and then work on it independently. When ready, they can ask the repository owner to accept the changes back into the main repository (“pull” the changes). The source management system will then compare the two versions of the files and merge them, resolving any conflicts where possible and reporting the conflicts that it cannot resolve.
Imagine if we could do that with content on a wiki. It is a whole new way of collaboration.
Ward’s federated wiki is a work in progress. He says that the concept will change and grow as people contribute to the project. The federated wiki, designed to allow new ways of collaboration, is in itself under development as a collaborative project on GitHub.
A wiki on a stick
Appfire has created Firestarter, a portable wiki appliance. It is a Confluence wiki on a USB drive. Why would a technical writer want a wiki on a stick? One scenario is to work on the documentation while offline. Perhaps on a long flight or in a remote forest cabin. Another scenario is to distribute the product documentation to customers on a USB stick, packaging it along with the product. The USB stick would contain the latest version of the documentation at the time the product is shipped. Firestarter can synchronize automatically with the server-based Confluence documentation whenever the customer is online. That way, they can get the very latest documentation even after the date of shipping.
Gaps in wiki functionality
While innovation is alive, there are gaps in wiki functionality too. Looking at Confluence in particular, the wiki lacks some tools that really should be there to make it the perfect platform for technical communication. Of course, we need to acknowledge that technical documentation is not the only use case for the wiki. The developers need to cater to other groups of users, too.
Here are some areas that spring to mind:
- Version control across a set of documentation
- Search and replace
- Comment management
Ideas for new wiki functionality
Here’s one of the ideas mentioned in Sarah’s book: Build your own albums in Confluence. Wouldn’t it be great if you could make your own quick reference guide by collecting pages from the product documentation? Just drag the pages you want into an “album” in your own personal wiki space. It would be even more awesome if you could drag in pages and blog posts from other Confluence sites, or even from Jira (perhaps you want to include a known issue and its workarounds) and other websites. This would be a neat way of compiling a getting-started guide for new team members, or of collecting material for a presentation. The “albums” feature request is logged as CONF-17025.
If you could compile a wiki wish list, what would be in it?
How to drive wiki development
So, now you’re dying to tell people about your requirements, and bursting with innovative ideas. How can you get changes, improvements and new features into the wiki software?
Let Atlassian know about your idea:
- Add a request to the Confluence issue tracker. This is the primary means of requesting a feature or improvement or reporting a bug.
- Join a user group.
- Use the contact form on the website.
Sarah’s book tells some good stories about features already developed with technical documentation in mind, where Confluence developers worked under close consultation with the technical writing team. Chocolate bribery is rife!
Talk to the development community. Plugin developers are beings of power. Find the developers’ contact details on the Atlassian Plugin Exchange. Choose the developers whose interests coincide with yours. Buy them chocolate.
Develop add-ons yourself:
- Write a user macro. You can define a simple macro by typing some HTML into a form on the Confluence administration screen – without having to add a plugin.
- Develop a plugin. A plugin is a more complex piece of software. To get a plugin working, you write the code and bundle it up in a JAR file, then install it onto the Confluence site. The Atlassian Developers documentation shows you how to get started with the Atlassian Plugin SDK.
- Interact with the APIs. Use the Confluence APIs to integrate the wiki with other applications and platforms.
Sarah’s book has some great examples of technical writers who are already doing all of these things!
Invitation from Sarah and Ganache: It has been a fantastic month exploring the technical writing world. We hope that you have both enjoyed and learned from these posts and excerpts from Sarah’s book. For those of you who still have an appetite for more wiki knowledge and chocolate please join us at the webinar to share more ideas on driving wiki development.
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.
Buy the book
Sarah’s book is filled with other creative tips and tricks for encouraging the use of your wiki and bringing your technical writing team together. The book also gives in-depth guidelines and lessons learned from all of the projects an events mentioned above. So, what are you waiting for? Buy the 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.
