Tim Anderson's ITWriting [Valid RSS]

Tech writing blog

Blog Home RSS Archives ITWriting.com
Add to Feedburner Add to Bloglines Add to Newsgator Add to My Yahoo

March 26, 2005

Using a wiki for documentation

Posted 3499 days ago on March 26, 2005

I've set up a documentation wiki for the HtmlEditor, a C# HTML display and editing component. I'm convinced that the wiki concept is an idea whose time has come; I've just written a brief comment on the subject for IT Week. This particular wiki simply documents a specialist control. The key strength of a wiki is that it enables collaboration; it is ideal for documentation since users can easily annotate or clarify problems they encounter. Here are a few reflections based on work I'm currently doing.

First, I'm writing about Borland's Delphi 2005, a fascinating but under-documented product. I wish Borland would set up an online documentation wiki for it. In fact, I wish Microsoft would do the same with MSDN. Of course someone needs to keep an eye on the edits to defend against vandalism; but I reckon the benefits far outweigh the risks.

Second, I've noticed that the wiki is giving me an incentive to do something I've intended to do for ages, which is put together proper documentation for this sample control. The wiki starts as an empty shell which invites you to fill in the detail; I find it compelling.

Third, leaving aside the collaboration angle, I reckon wikis are the easist way to author web sites. Type a non-existent link, save the page, then click the link to create the missing page. No upload process as you are working with live content. If you make a mistake, just correct it; or wait for someone else to do so.

Fourth, wikis are a much better way to organize collaborative content than the other two common schemes, mailing lists and discussion groups. A wiki can get disorganized and out of hand, but at least it supports the idea of cross-referenced, indexed content organized into topics. Searching lists and groups is crude by comparison.

It's important to keep this in perspective. Wikis are not the answer to every need, nor do they replace the traditional CMS (Content Management System). However, I do think the wiki concept is under-exploited at the moment.

Incidentally, after a quick bit of research I used DokuWiki, a PHP solution. I was also interested in ASP.NET wikis, but DokuWiki seemed to fit the need best and was very easy to install. However my research was sketchy, and I'd be interested in hearing from others who have set up wikis: what implementation did you use, and why?



Re: Using a wiki for documentation

Posted 3499 days ago by Tim Anderson • • • Reply

Thanks for the link - I had a quick look at FlexWiki. I should explain: I have a shared-host public ASP.NET server, but I don't have full control, eg I can't create new virtual directories. I wasn't sure whether FlexWiki would work. Second, I think DokuWiki has a nicer editor. But FlexWiki looks good and I'll have a closer look when I have a bit of time to experiment.


Comments are closed

Recent posts

Users plead with Borland to give up .NET
IE7 to be released 18th October,...
If Microsoft doesn't use UAC, why...
Google's unsettling lack of direction
Vista security: now prove it


Powered by bBlog