Wiki makeover

J the TW writes on Spacebar about some wiki restructuring that she is about to undertake. Her blog post struck a strong chord with me, and probably will with a number of other wiki-huggers out there. When a wiki gets to be of a certain age, it needs some work done. In some cases, it may even need an extreme makeover. Who else has a story to tell? And should you even try to put structure in a wiki?

My wiki makeover story

Like J, I have just passed the 6-month mark at my new job. Writing in and managing a wiki is a large part of what I do. One of ‘my’ wikis needs some body sculpting. It’s been around quite a few years now, and parts of it are looking a bit tired. I’m thinking a face lift, a fair bit of liposuction, plus definitely some implants and enhancements.

The wiki in question houses the technical documentation for the Confluence software product. Yes, it’s a wiki which documents a wiki. It’s the oldest of our product documentation wiki spaces, and is updated continuously by a large number of people. It has kind of grown organically, to match the needs of a fast-growing company plus a rapidly-expanding software product. The wiki pages are updated by technical writers, support engineers, developers, sales staff and anyone else within the company who sees something that needs doing. In addition, anyone in the whole wide world can add comments to the wiki pages. These comments often contain useful information, which should ideally be incorporated into the pages at some time.

Enter the technical writer. It’s definitely within my portfolio and skill set to re-organise the documents, excise the out-of-date pages, add missing bits and sort out the structure.

Two hiccups are immediately obvious:

  • Time: It’s hard to fit in a large maintenance task like this, especially when there are new features rapidly and continuously appearing and demanding to be documented.
  • Sustainability: With so many different authors, the wiki will tend to revert to its current muddle soon after the restructuring task is done. (Is it ever done?) That’s entropy, man.

Should you even try to structure a wiki?

It’s a good question. It’s even a philosophical question. Isn’t a wiki meant to be an amorphous collection of pages which the reader can surf via a search engine, an index, RSS feeds and page-watches to catch the latest updates, or even just via the lucky-dip technique? Isn’t a wiki kind of like a mind map, with free-thinking links darting here, there and everywhere? You could compare a wiki to the nutrient soup which purportedly gave rise to sentient life. A wiki enthusiast might justifiably believe that we should not impose a hierarchical structure on the wiki gloop.

Well, my answer would be: ‘Yes’, wikis make excellent nutrient soup which allows ideas to bubble up to the surface and be scooped up by a passing RSS feed. But ‘Yes’, you can also add structure to allow human readers to browse in a more methodical way when that suits them. To some extent, it depends on the purpose of the wiki concerned. When the wiki contains technical and support documentation, structure is a plus.

Some examples of structure might be:

  • A table of contents.
  • Division of documents by audience.
  • Page hierarchies, so that you can group pages which deal with the same topic.
  • Headings within pages.
  • Similar look and feel across the pages which deal with the same subject.
  • And so on – your typical tech writer stuff.

We have some other wiki spaces with good structure. Here’s an example.

Quelling the hiccups

If your structure has some logic to it and is readily visible, then other people will tend to follow it rather than add to a spaghetti-bowl of documents. Our brains are wired to recognise patterns, and we usually like contributing to the symmetry rather than breaking it. Technical writers are trained to chunk information and to present it in ways which appeal to other humans. So all we have to do is to apply these techniques to a wiki. That takes care of the ‘sustainability‘ hiccup. Easy 😉

The ‘time‘ problem is less easily solved…

Watch this space

I’m planning to get to work on the Confluence wiki. Probably the best thing is to tackle it in manageable pieces. I have a few tasks mapped out already. Let’s see how it goes! If J the TW beats me to it, I’d love to hear her story!


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 12 January 2008, in Confluence, technical writing, wiki and tagged , , , , . Bookmark the permalink. Leave a comment.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: