Re: Wiki as a documentation delivery system

[Sean Wheller <sean -at- inwords -dot- co -dot- za>]

On Saturday 29 July 2006 00:31, Carol Kiparsky wrote:
> Have you had experience using a Wiki as a means of delivering
> documentation and getting input from your customers? I am planning such
> a project, but have no experience beyond reading wikipedia!  I plan to
> start with our internal implementation guides, then expand to external
> docs on the wiki for internal review, and finally open the external docs
> on the wiki for customer use and feedback.

The concept does work in practice. Many open source projects use wiki in the 
manner you describe.

>  
> I think putting docs on a wiki is a wonderful idea, but I have some
> concerns:
>
> 1. First of all, formatting and navigation.  Our current documentation
> is WebHelp and PDF, and the formatting used is very valuable in
> conveying information.  Wiki pages have minimal formatting, at least as
> far as I have seen.  I am not happy at the prospect of recasting all
> this documentation in Wiki format.  Nor would it be a good idea to open
> the source files (HTML, so technically possible) to direct editing by
> others.  Have any of you dealt with this issue? 

Your concern is justified. I like to call wiki a "Content Motel," everything 
checks in, but never checks out. Once you have content is wiki you must find 
ways to get it back out of wiki in a manner that does not create additional 
overhead.

>
> 2. What about context sensitive help? Does it figure in the wiki in some
> way?  

No

>
> 3. I guess what I would like is the best of both worlds:  The
> interactivity of the wiki, with the rich formatting and navigation of a
> more usual help system.  Maybe it would be best if reviewers (internal
> and external) could comment by annotation instead of directly revising
> the text. Does a wiki support this?  Or is it not a good idea?
>
> I would appreciate suggestions and tales of your experiences.  

We are building a wiki-like system that will enable through the web-based 
editing of docbook xml sources. Under lying this is a Subversion repository. 
Above this is a CMS.

-- 
Ask me about the Monkey.

Sean Wheller
Technical Author
sean -at- inwords -dot- co -dot- za
+27-84-854-9408
http://www.inwords.co.za
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.