h1

Wiki for docs

February 7, 2007

I received email from a few folks suggesting I look into the use of Wikis for technical documentation. Does anyone have direct experience doing this, and if so, how did it go?

I find the idea intriguing. Clearly, wikis have been a great success with reference material, like Wikipedia, and I’ve found some to be very useful, for example the DocBook WIKI. I particularly like the idea of using a Wiki for fast moving, customer driven information. For example, a Wiki FAQ could be a great substitute for, or supplement to, support forums, which are not one of my favorite forms (there’s just too much junk, too little structure, and too little moderation in most forums). This is already popular for general topics (check out wikifaq.com for one interesting general purpose FAQ in Wiki form), and I’ve seen it used for open-source software. Does anyone know of an example for commercial software or other products?

Using a Wiki for commercial products poses a different challenge, since there is an expectation, in fact a legal obligation, that documentation will be accurate (or at least that you will exercise due diligence to make it as accurate as possible). Opening up your documentation to any yahoo to update doesn’t strike me as exercising due diligence. So, I expect that to use a Wiki, you will need to be very careful and clear about where you open up access and where you don’t.

However, I think there could be a powerful hybrid between traditional documentation and Wiki-style documentation. How about having a base of docs that is locked down (or at least moderated) for outside access, but open for free access to the technical documentation team, plus an open Wiki area, including a FAQ, that anyone, or to be conservative, registered users, can update? The technology wouldn’t be a problem; all the pieces are easily available and could be put together with little difficulty.

The biggest challenges would be moderation, including the ability to respond quickly to wiki-spam and other anti-social activities, and (maybe bigger) getting management acceptance for the idea that the documentation can be changed instantly by any technical writer (it wouldn’t surprise me to find that many would have a harder time giving that power to their writers than to their customers).

On that happy note, I’ll leave the question open. Feel free to post a comment with your thoughts.

Advertisements

5 comments

  1. I believe some wikis allow you to associate significant status to a page, or even a page section, so that you might be able to tag a page or section as having been changed but not yet reviewed or approved (sort of a read at your own risk), or have some sort of workflow where changes have to be “vetted” by someone authorissed to approve changes. And of course you’d need to integrate change control into your wiki (many have this) so you could roll back in the case of a really egregious change.

    I think wikis are useful and cool, but don’t really provide anything new in the way of organizing material that hasn’t been achievable or done before. It’s not just the content, but how the information is structured and organized so I can find out what I want to know, including all I need to know, conveniently.

    Maybe a hybrid approach- Macromedia (now Adobe), has a “livedocs” site where the official technical docs are available, but each page can also be commented on by users, and the comments are collected and displayed at the bottom of the page.

    The key problem I’ve always had doing technical docs is lack of contact with the customer- the feedback. Wikis could provide a way to get that feedback, but I don’t necessarily want customers rewriting the docs, either.

    In summary, I’m not really sold on wikis for technical docs that are publicly available. I think the structure and organization (is it task-oriented, for example, or organized some other way) is more important than if you present it as a wiki, or web pages, or even a dead tree.


  2. I think you’ve nailed the critical point; wikis are cool, but they don’t replace good writing and structure.

    Where they’re a big win, in my view, is that they make it much easier to carry on a conversation with customers (of course, blogs, forums and mailing lists do this, too), and they make these conversations visible to other customers, rather than hidden in one-on-one email, snail mail, or phone conversations.

    Of course, you only reap the benefits of customer interaction if you put effort into that interaction by responding to customers and keeping them engaged. That’s another constant that transcends media.


  3. I’ve been using it to get documentation reviews out of some of my remote engineering teams.

    I’ve had mixed results…I found that I really had to stay on top of things… for example regularly reminding the reviewers to use the wiki, and to check and recheck their input to see what new/additional comments have been inserted later…


  4. I’m now in an organization that is using wiki’s for internal communication. It’s useful to the tech writers as it’s a developer to developer communication that the writer can tap into. One of the drawbacks is monitoring the wiki for changes, writers don’t necessarily know how to use RSS and not all wiki pages have it available.


  5. I think Wiki can be good aggregator to drive technical documentation process. In my experience of PLM Software, documents combined of 3D models (normally comes from CAD), Visualization, additional content. What I like in Wiki is capabilities allowing to multiple people to be involved into process of documentation. After, technical writer can produce final documents.



Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s

%d bloggers like this: