ffeathers — a technical writer’s blog

Can you use a wiki for technical documentation? Yes!

Is it a mindshift? Yes!

Is it fun? Yes!

Am I a wiki hugger? Yes!

I’m a technical writer with nine years’ experience. I’ve used many tools of the trade, including Microsoft Word, Adobe Acrobat, RoboHelp, XDK, Help and Manual, HTML Help, QuarkXPress, Documentum, Lotus Notes / Domino and Microsoft SharePoint. And now I’m using Atlassian Confluence, a wiki. Yes, I’m biased, but with good reason

Writing technical documentation on a wiki is what I do every day. Here’s an example. So I’ve decided to write a few blog posts about it. This post is one, and there are more to come. So watch this space.

Like other media, wikis have a lot of advantages and also some quirks. Treat your wiki right, and it will come through for you. Often it’s a matter of recognising a wiki’s strengths and using them in a creative way to perform or even replace a more traditional function. For example, you could try using labels/tags to generate:

• The index - see my previous blog post.
• Lists of ‘related topics’, which we often put at the top or bottom of an online help topic.
• Frequently asked questions (FAQ).

So, let’s get down to the nitty gritty.

First, you might have the luxury of choosing your wiki.

Here are some things to consider:

• Does your wiki allow you to restrict access to the pages, and what permission levels does it allow? For example, you might want to prevent anonymous users from seeing anything at all. Or you might allow everyone to view your pages, but only logged-in users can comment on them and only users belonging to a certain group can add, edit or delete content.
• What overall structural framework does the wiki provide, to allow you to organise your manuals, chapters and pages?
• How easy is it to structure the information within a page using styles, headings, frames, etc?
• How easy is it to upload and insert images?
• Does the wiki let you export/download the content into another medium, such as PDF or HTML?
• Do you know anyone who is using a wiki for technical documentation, and can you get some tips from them? Alternatively, take a look at some of the documentation already published on a wiki. I’ll put some examples at the end of this post.
• Does the wiki keep a history of changes to a page, and allow you to revert to a previous version?
• What tools are there to help your readers find information, such as indexing, table of contents and search?
• Does the wiki allow customisation - at the highest level of adapting styles and presentation, and at the deeper levels of allowing you to add plugins, change the default page layouts and even change the source code?
• How vibrant are the developer and user communities - is there ongoing development and support of the wiki?

Here’s a really useful tool: WikiMatrix lets you compare wikis. You can even your own requirements to see which wiki is best for you.

Now that you have a wiki, start planning your documentation:

• Consider the overall structure of your documentation suite, much as you would plan a user guide or a set of documents written in Word or something else. Plan how that structure will fit into the wiki’s framework. For example, you might want to write a user guide and an administration guide, each consisting of sections, chapters and pages. Will you put each guide into a separate instance of the wiki? If you are using Atlassian’s Confluence, you might consider putting each guide into a separate ’space’ (a sort of wiki within a wiki). Or you might use a space to collect all the documents for a particular product - that’s the route we’ve chosen. For example, our Crowd space contains the user guide, administration guide, installation guide, etc.
• Think about the structure of each page. If your wiki allows you to create templates, that’s useful. But a light touch is best here. Given that you’re probably going to have multiple authors with different styles and skills, I’d go for overall consistency of look and feel rather than detailed content-level standardarisation.
• Think about the style and character you want for your documents e.g. formal or chatty, stylish or basic. Tailor your use of styles, macros, colours, etc to suit this character. In the list of wiki documentation sites at the end of this post, you’ll see a few different styles.
• Plan your permissions - who should be able to do what. We allow all Atlassian staff full edit rights. Non-Atlassians and anonymous users can add comments and of course can view the pages.
• Remember that it’s a wiki, so its power lies in its flexibility and dynamism. Don’t lay down too many rules, and do allow as many people as possible to edit the pages.
• Have you hugged a wiki today? Get intimate with your wiki’s capabilities and tools. If your wiki allows you to install extra plugins and macros, get to know them too. This will help you quickly find a solution to any questions that arise.
• Think about your labels or tags carefully - plan them as if you were planning the keywords for an index in a more traditional type of documentation.
• You, as the technical writer or person who owns the documents, should subscribe to an RSS feed or a watch-list of all changes and comments. That allows you to monitor what’s happening and tweak the content if necessary.

Jump in, create a page and start writing.
Some examples of technical documentation published on a wiki:
Atlassian’s documentation and discussion site
Atlassian Confluence Hosted Administration Guide
Atlassian Crowd documentation
Adaptavist User Guides
GigaSpaces
Ubuntu User Documentation

I’ve run out of time - if anyone has any more examples, I’d love to hear about them.

Watch this space:

Do you feel that this post has raised more questions than it’s answered? I hope it’s given some good starting points. And stay tuned for more - I’ll expand on some of the points in my next blog posts.