Wiki docs – the challenge and the call

Calling all technical writers — are you a wiki hugger already, like me 🙂 or just getting interested? Let’s get in there and make our voices heard. We’re in the front line, writing technical documentation and pushing it out to readers in far-flung corners of the world. Wiki technology has been around for a while, and many wiki developers are looking for new things to do with their product. New features and innovative mashups appear almost daily. Let’s speak up, tell them what we like, and help make wikis even better.

endithinks commented on my previous post, asking what the challenges are and when it would be inadvisable to use a wiki. And Don pointed out a couple of problems we’ve had to work around, when using a wiki for document management. He also identified the tree in my photo. Thank you, guys.

So, what does a wiki not do very well? Should it be doing those things at all? And what’s happening in that sort of arena?

A wiki is not a document management system. It’s not meant to be. If you need strict version control and records management for purposes of legal or other compliance, then you’d probably stick with a more traditional document management server, such as Documentum, Lotus Notes, SharePoint or what have you. Also, if you have a large existing base of documents in other forms, it would be cumbersome to upload them to the wiki and then ask your readers to view them as attachments to wiki pages. Instead, you might use a wiki as a knowledge management system running alongside your document server.

Keep an eye on the new stuff happening:

  • Atlassian and Microsoft have announced a Confluence-to-SharePoint connector. This is exciting for those of us who know and love 🙂 Microsoft SharePoint. The connector is very new, so it’s a free download while still in beta. If you’re interested, try it out. I think that this is a great time for technical writers and SharePoint power-users to have their say on what the Confluence-SharePoint integration should do. It’s a bit basic right now.
  • An intriguing snippet of information in a comment from xaop on a blog post by Craig (2nd comment in the list) mentions integrating their Docbook publishing process from Subversion into their project website, so that customers can link tickets, wiki pages and comments into the docbook. I’d like to know more about that one.

Wikis don’t really do workflow. In most cases, a wiki is for instant gratification — view, edit, save, and bob’s your uncle. But again, things are on the move. Here are some new developments I’ve come across. Let me know if you’ve seen others.

  • Comala Tech have written a workflow and approvals plugin for Confluence.
  • Atlassian is working towards the launch of JIRA Studio, which will allow people to use Confluence (wiki) and JIRA (project management and issue tracking) on one integrated platform. There will be some interesting source control and review tools in there as well.

Wiki editors are not always easy to use. Many of them rely on wiki markup, and there’s not much standardisation of the markup codes used in different wikis. But things are on the move:

  • DITA Storm offers a browser-based DITA XML editor which you can embed in your web application.
  • A number of wikis offer WYSIWYG editors.
  • I’ve used Confluence and Twiki. I much prefer wiki markup to a WYSIWIG editor. But many of my colleagues swear by the WYSIWYG editor.

I’m a self-professed wiki hugger, and I’m not alone in that. A wiki has a certain charm and gives ‘everyman’ a sense of power (that instant gratification again). And wikis do a lot of things very well indeed. Because wikis are the flavour of the month, even after being around for a few years, they’re growing and changing apace. Now’s the time to have a say in their development.

Let’s make ourselves heard. Download a wiki and try it out. Most wikis let you try one for free, and some offer an ongoing free personal licence.

Make a fuss about the things that wikis are missing (see all the comments on and the votes for this requested Confluence improvement) and pat the developers on the back for the bits they get right. Let them know we ♥.

If you’re interested in more ideas and experiences in using wikis for technical documentation, read some of my other blog posts on wiki docs and watch this space — more coming. Also, wander over to Anne Gentle’s blog and search for other wiki writers’ blogs.

There’s a lot more happening. Let me know what you’ve seen and done.


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 24 November 2007, in atlassian, Confluence, SharePoint, technical writing, wiki and tagged , , , , , , , , , , . Bookmark the permalink. 3 Comments.

  1. I have used Confluence for a while. You should be technically advanced to use it. Most of my colleagues are top-managers of IT companies, but I have never seen a person who can create a page with documents attached to it in 5 minutes.
    And you probably know how they made revisions tracking. You have to upload it under the same name to create a revision! Who could imagine…
    But I like wikis. I have even made a post recently to give a vote for enterprise wikis:

  2. Well, you’re not alone in liking wikis. We think wikis are a great way to collect knowledge about our profession, so our site, is wiki based. Feel free to add to our knowledge base of articles and links and calendar events. We have an ongoing (editable) article about Wikis as End-User Documents.
    –Bill Albing

  1. Pingback: Craig's Musings

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: