In our previous post, we took a somewhat light-hearted, somewhat serious look at at day in the life of a technical writer. This week we will introduce you to one of the 5 Cs of technical communication: Collaboration!
Collaboration – that’s what a wiki is designed for. Imagine an ideal world, where technical writers design the structure of a documentation set and create the first version of the documents. From that point on, the subject matter experts share the task of maintenance, giving the writers more time to develop new documents. We all focus on what we know best. What a dream!
In the real world, it takes some managing. Like all good things, collaboration can be a messy business. And like most messy things, the rewards are worth the effort. In this post we share what we’ve learned from our experiences with collaborative document development.
Updates by everyone
We develop and host our documentation on two Confluence sites: the Atlassian documentation wiki and the Atlassian Developers site. The pages are continuously being updated by developers, support engineers, marketing engineers, product managers – even a CEO or two. Most of the authors are Atlassians. Only seven of them are technical writers. We also have around 50 community authors.
One of the greatest benefits of Confluence is that it allows collaboration that transcends geography. With offices around the world, it is essential to have a documentation base that people can update at any time, sharing information with colleagues who are asleep when we are awake. The wiki works around the clock.
So, with the power of the wiki on you side, what should you consider when preparing to open up your documentation for updates and comments by everyone?
Image is copyright © Ryan Maddox, 2012
With a great wiki, comes great responsibility
- Permissions: You’ll need a tool that allows you to define groups of people – technical writers, company staff members, community authors, and so on – and to assign permissions to each group. Confluence’s permissions scheme is robust and flexible, yet not so complex as to be daunting. For technical communicators, the space permissions are especially relevant.
- Monitoring and notifications: You’ll want to subscribe to an area of the documentation, so that you receive notifications whenever someone updates a page. In Confluence, you can keep track of updates by watching a space or building an RSS feed.
- Copyright and intellectual property: You will need to display a suitable copyright license on all the pages, so that the contributors and the readers know their rights. We use a Creative Commons Attribution 2.5 Australia License. It’s also a good idea to ask contributors to sign an agreement, signifying that they understand the intellectual property arrangements for the content that they contribute. The Atlassian Contributor License Agreement is based on the Apache Contributor License Agreement.
- Encouraging people to contribute It’s safe to say that you won’t be deluged with updates. Instead, invite people to update the documentation and keep telling them how much you appreciate their contributions. Make it clear to new readers that contributions are welcome
- Style guides, templates and structure: This is a bit of a balancing act. Too much structure can deter contributors. Yet everyone appreciates some guidelines. Templates are very useful, especially in banishing that dreaded empty page that needs filling. A light style guide is useful to external as well as internal authors.
- Deleting contributors’ content: Sometimes a contributor may add a page that is unnecessary or incorrect. They may have missed the fact that the information already exists somewhere in the documentation set, or they may have made a mistake and added the page in the wrong place. The technical writer will need to remove or move the page. It’s important to preserve the trust of the contributors. In some cases, you may need to keep a copy of the page. Then thank the contributor for the information and explain where you have put it.
Sarah’s book covers the above points in detail. You’ll also find information in our guide to managing the lifecycle of your technical documentation.
Get everyone engaged with comments
From Sarah:
“When I started working on a wiki a few years ago, it was the first time I had experienced near-instant feedback from readers. Even now, a few years later, being able to ask for and respond to people’s feedback still feels like a luxury and a privilege. And some comments brighten my day.”
People give us feedback on the Atlassian documentation wiki by adding comments to the pages. This feedback enriches both the documentation and our understanding of our customers. It shows us how people use the product and what they expect from the documentation. It gives us the opportunity to improve the documentation via direct contact with the readers.
This is what we have learned about managing comments:
- Numbers can be overwhelming: People are more likely to add comments than to update a page. You’ll need to ensure that management understands the number of people required to handle such input, and a plan for dealing with it.
- Not all comments are about the documentation: Comments come in all shapes and sizes. In our experience, most comments are calls for help rather than points about the documentation. It’s therefore useful if the support team and developers can help respond to the comments.
- People help each other: The most rewarding thing of all is that people help each other. Someone asks a question, someone else answers, and everyone benefits, without the technical writers needing to intervene.
- A pilot project is useful: If the number of readers is large, it is a good idea to run a pilot project to measure the amount of feedback that you can expect and to judge how much time you will need to spend responding to it.
- Plan who can do what: Decide who should be able to add, respond to and remove comments on the documentation pages. Using the Confluence space permissions, you can assign the right to add or remove comments.
- Consider how to respond to comments: Be direct and positive, professional and polite. It’s OK to be light-hearted when appropriate. Be real and honest. Remember to thank people for their contributions.
- Decide how long the comments should remain on the page: Once a question has been resolved, let the comment and response remain on the page for a given period. At Atlassian, we aim for a week. Then remove both comment and response. This keeps the documentation tidy and readable.
There are other ways of gathering feedback. For example, instead of allowing comments you can offer a feedback form on every page, as we do on the Atlassian Developers site. There are pros and cons to both methods. A big advantage of comments over feedback forms is that readers can see and respond to each other’s comments. People can instantly benefit from advice from other readers.
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
Things are just getting interesting as we continue to probe the magical world of technical documentation. Next week we’ll show you how you can turn your ordinary documentation into extraordinary forms of communication.
Buy the book
The above pointers just brush the tip of the iceberg. Sarah’s book describes the various methods of gathering feedback, including forms supplied by plugins and add-ons, and external forms designed via online form builders. She also discusses techniques for minimizing spam and gives some statistics of comments received.. Buy Sarah’s book Confluence, tech comm, chocolate: A wiki as platform extraordinaire for technical communication today!
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. And add-ons for Confluence for technical documentation enhance its power as a complete technical writing solution.
