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 4644 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?



FlexWiki

Posted 4644 days ago by flipdoubt • • • Reply

FlexWiki, of course, is where I would have gone: http://www.flexwiki.com/http://www.flexwiki.com/

I like that Craig makes pretty regular blog posts about what goes into the effort to produce FlexWiki and its supporting components.

Re: Using a wiki for documentation

Posted 4644 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.

Re: Using a wiki for documentation

Posted 4644 days ago by Jonathan Hodgson • • • Reply

Absolutely agree that wikis can work really well for documentation / knowledge sharing. I wrote an article on the codeproject.com which describes using the OpenWiki implementation, www.codeproject.com/asp/wiki.asp. There is now a newer version called OpenWiki2004 at www.openwiki.info/, but I haven't looked at that yet. Both are ASP based. Jim Griesmer who works on the Visual Studio team mentioned at they are moving alot of their specs. to wikis, http://blogs.msdn.com/jimgries/archive/2004/02/14/72914.aspx#FeedBack

Re: Using a wiki for documentation

Posted 3294 days ago by Rajdeep Gupta • • wwwReply

I am using the open source tool Joomla for developing wiki based documentation. Initially played around with couple of other tools but settled for Joomla. Its very easy to install and within few readymade steps, you are ready to go...I am presenting a paper on this in the upcoming STC India Annual conference @ Pune, India.


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