This is the first of a series of posts from Atlassian’s Technical Writing Team focusing on using a wiki for technical writing. In this post, I’ll be talking about the reasons why a wiki is a good solution for your technical documentation needs. Following posts will cover how you can author, publish, structure and manage your documentation on a wiki.
Wikis had been around for more than ten years when I joined Atlassian, yet I had never considered using a wiki for documentation beforehand. You may be in the same boat. Well, hop out of that boat and join me on the wiki bus! There’s more to wikis than online encyclopaedias.
“Wikis are fun, but not for serious documentation.”
A wiki is basically a website where content can be easily added, modified and removed by any number of users. This makes it great for your team to collaborate on stuff, but you’d never want to show that mess of ideas to your customers, right? Well, that’s what I thought.
The truth of the matter is that wikis are just as capable of supporting a comprehensive suite of documentation as traditional publishing or CMS tools. A wiki can carry out document versioning, content re-use and structure, release management, single sourcing, publishing and more. We’ll be covering these topics in more detail over the next few weeks, but here are a few of the benefits that I’ve discovered from using a wiki for documentation.
1) It’s good for you (the technical writer)
Writing documentation in a wiki can be a revelation, if you’ve been using a traditional writing tool where publishing is a multi-stage process. Want to fix a mistake on a page in the live documentation? Just open the page, edit it and save. It’s as easy as that.
The editing experience can also be more forgiving than that offered by some HTML or XML editors. Many enterprise wikis, such as Confluence, bundle rich text editors that remove the need for you to wrestle with complex markup. It’s a relief to be able to get on with the business of writing, rather than hunting down that one missing tag that’s breaking a document.
It’s not just the writing and publishing processes that are made easier with wikis. Gathering the information to write a technical document is often a collaborative effort between the product managers, developers and myself. Simply putting up an early draft for review often results in a wealth of useful feedback, as other people drop comments on the page or update the draft themselves. I can then selectively incorporate feedback or roll back changes, as desired.
2) It’s good for your customers
Most wikis have the traditional documentation tools that help time-poor customers find the information they need, e.g. powerful search engines, tags/labels, bread crumbs/navigation trees, etc. Wikis can extend beyond these functions to provide customers with richer content. Is it easier to demonstrate a concept than explain it? Try adding a video to your document. Need to describe a complicated procedure? Just embed a process diagram into your wiki page. Addons and plugins can be used to add innovative features like these and more, to many basic wikis.
If you are worried about providing your documentation to customers in different formats, don’t be. Many wikis provide you with the option of exporting your documentation to a variety of formats. We export our documentation to PDF, HTML and XML. Different styles can also be applied to each export format, allowing documentation to be customised to suit your audience.
Documentation maintained in wikis can even help improve customer support. Our support staff often update and add new documentation, ensuring that customers are reading up-to-date information. A wiki can also provide another valuable feedback channel for customers. Comments added to pages often alert us to problems with the documentation or with the applications themselves.
3) It’s good for your company
Do you feel nervous at the thought of customers adding angry comments on your documentation wiki? Spammers running riot? Here’s the flipside for you to consider: customers answering other customers’ questions in the wiki, external developers adding code samples to help flesh out your document, partners volunteering to write new documentation. A well-maintained documentation wiki can help foster a customer community. Good enterprise wikis will provide you with tools, like granular permissions, CAPTCHA and spam filters, to let your community get involved safely with your documentation. Many organisations already maintain their documentation on a wiki — check out this great list of documentation wikis compiled by Anne Gentle.
Finally, the bottom line. Some wikis provide more functionality than other wikis, at a price. For example, granular permissions are usually a necessity when maintaining enterprise documentation on a wiki. This is a feature that you probably won’t find on open-source wikis. However, you’d be surprised at how competitively-priced wiki solutions are. If your technical writers can take advantage of the benefits described above, you may be able to streamline your entire documentation process. Your company may end up paying a fraction of the cost that it pays now for its documentation.
It’s worth investigating and we’re going to help you. Over the next few weeks, Atlassian’s Technical Writing Team will be publishing a series of posts, each exploring an advanced topic. Next week, Giles Gaskell will take an in-depth look at publishing. Stayed tuned as we share our experience in authoring, publishing, structuring and managing technical documentation in a wiki.