Re: a survey on help systems

[John Cornellier <jcornellier -at- abingdon -dot- oilfield -dot- slb -dot- com>]

We just did a pilot project where we used TWiki (www.twiki.org) to 
develop the help. For those of you who are new to this, a TWiki is an 
implementation of a wiki, and a wiki is a web site that can be edited 
from your browser, and includes such functionality as versioning, user 
control, etc.

We were already using Twiki for widely for collaboration e.g rather than 
circulating Word documents around with ammendments and whatnot, everyone 
edits a page on the wiki.

So we actually wrote the help system in Twiki, as series of web pages. 
It was quite successful in terms of getting input from the software 
engineers. People appreciated having a pretty reasonable preview of what 
the CHM would be like in terms of structure and appearance. The only 
downside is that the editing environment is a bit primitive, but then 
our doc doesn't have much formatting. Also no equation editor.

Once the content was finalised, we ran some scripts and output the wiki 
into a series of interlinked HTML files, which then were compiled into a 
CHM.

We have another projects using D2H or RH. On the positive side, people 
can edit in Word, which is not a challenge to them, but the negative 
side is that someone editing an indiviual doc can't get a picture of the 
whole help system. I have never been too much in favour of that workflow 
as it puts too much ownership of the authoring process in the hands of 
the techwriters. IMO the tech writer should be able to share authoring, 
while owning the publishing side of things.

That said, we have another project where we're deploying XMetal + DITA + 
MathFlow + FOP and that does require a steep price of entry to do 
editing. So there we're hoping to deploy a "lite" editing interface 
using a smaller & cheaper XML editor (oXygen? XML SPy?)

John Cornellier

A.H. wrote: