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.

I’ve spent a fair bit of time as a book indexer. For a couple of years, I was leader of the Association of Southern African Indexers and Bibliographers in the Western Cape. A few books have my name printed inside the front cover. You might find one on your coffee table.

A BTW: So there are people who create those indexes in the backs of books? Can’t we get computers to do that? Yes, there are professional indexers out there. And no, computers don’t do a good job of it, though indexers do use custom indexing software to speed up the process.

Now I’m writing technical documentation on a wiki.

Indexers like things to be clear cut.

• They worry about things like this: Is it better to say “books, indexing of” or “books, and indexing” or just plain old “books, indexing”?
• They are proud that their index includes precisely the correct terms, and that each term points directly and unequivocally to the relevant page(s).

Take a wiki. Content is dynamic and slightly chaotic. You may write a page that is perfect and precise. Next time you look at it, someone has changed it. The other person sees things slightly differently to you, so your nicely defined concepts have morphed a bit. Someone else adds their viewpoint, and the concepts are now definitely squishy (in your own view, anyway).

How can we fit something as precise as an index into something as fluid as a wiki?
What tools does a wiki provide for creating an index?

Enter the ‘fuzzy index’

(Cf. Wikipedia’s definition of fuzzy logic.)

Since wiki content is constantly changing, any index is bound to be slightly less reliable than in a more controlled environment. So why not go with the flow. Instead of concentrating on precision, the wiki index could aim to:
(a) include all wiki content in the index in some form or other, and
(b) help readers to find the information they need, by methods other than the traditional alphabetical and hierarchical index.

Here’s a plan:

1. Use keywords (metadata, tags, labels – whatever terminology your wiki uses) to indicate the main point(s) of your page.
2. Encourage other people to add their own keywords too – especially if they change the content of the page.
3. Use some sort of visualisation technique, based on popularity or relevance of keywords, to help readers find the content which is most relevant to their needs.
4. Make sure that the wiki’s search engine can include the tags/labels/keywords in its search results.

Here is an example using Confluence’s labels to form an index. Click the images to expand the screenshots.

Labels (tags, keywords, metadata) applied to a wiki page (near top left):

All labels, displayed alphabetically, forming a traditional-looking index:

Labels ordered by popularity (i.e. number of times the label is applied to a page) – a sort of cloud:

List of pages which have a particular label, displayed when you click a label on one of the above two screens:

Search results, including labels which match the search term (near top left).

Of course, if you do need precision and tight control of your content, you can lock down your wiki pages via the permission settings (which just happen to be the topic covered in the above screenshots). This will prevent your concepts going squishy and make your index less fuzzy. It all depends on the purpose and character of your documentation.