Cross-platform end-user-help authoring tools

Question

What are some good authoring tools for creating cross-platform help files for end-users? (Our application is using the Qt framework, if that makes any difference.)

Note: I'm not interested in internal API documentation--we're using doxygen for that.

Ideally, a solution would:

• Allow us to manage all help content (text, table of contents, images, etc.) in a single location.
• Output to native help formats. (CHM for Windows--or at least something we could feed directly into the HTML Help API; not sure what other platforms' "standard" help formats are.)
• Decent WYSIWYG support: handle common text entry, images, cross-references, etc. easily, but we can edit the HTML when we need to.
• Text-based file-format for help project (XML, etc.) so that it can be versioned in Subversion.
• Any hooks that help keep it in synch with the actual code base would be great. (Perhaps somehow a help topic is associated with a code file, and can check Subversion to see if any changes have been made and flag a topic as "possibly out of date" ... am I dreaming?)
• Help content can be localized.
• Not opposed to commercial product, but a free option would be nice.

I'll go ahead and make this a wiki and start with a few examples. Vote 'em up or down if you have experience with them, and leave some comments. Add additional tools as well.

Answer 1

Robohelp

Answer 2

Help & Manual

Answer 3

I just discovered Sphinx; I think I'm in love.

• Better than WYSIWYG over HTML: reStructuredText
• Outputs to QtHelp (among other things), so will be easily to distribute (and integrate) in our application.
• Not sure about localization yet, but we'll cross that bridge when we need to.
• Was easy to set up and "just works"; looks professional.

Answer 4

The only one I know is Latex, one of the latex2html converters, and then a few adaptation to make the resulting html ready for the CHM archiver.

• text,html,chm,pdf, ps no problem.
• Converting to Word via RTF used to be a disaster, don't know current status.
• latex 2 html converters, while several, all have their own problems.
• The pdfs look absolutely great.
• WYSIWYM (via lyx) possible.

This archive has a bunch of CHMs that way (notably the prog,ref and user parts, the rest (rtl,fcl,lcl) are generated by our own doxygen equivalent, fpdoc)

http://www.stack.nl/~marcov/doc-chm.zip

Note that the above CHMs are made with our own (portable) CHM compiler. Yes, no more workshop.

A Lyx document as PDF and html:

pdf: http://www.stack.nl/~marcov/buildfaq.pdf

html: http://www.stack.nl/~marcov/buildfaq/

Answer 5

I have used robohelp for years.

It is fine, but the core technology is very old now. Also the way they lock to Word versions is a total PITA (and has forced me to avoid MS office upgrades several times).

We are moving to madcap flare http://www.madcapsoftware.com/products/flare/robohelp.aspx

Answer 6

I think DocBook addresses all you requirements except possibly the synchronisation hooks, which I'll think a bit further on. It's essentially a subset of XML designed for creating documentation, and is free and open source. It's just a format plus a set of XSL output transforms that convert the Docbook into more useful formats (HTML and thus CHM, JavaHelp, PDF via XML-FO or Tex).

This means that you still need to choose an XML authoring tool to actually edit it so things like WYSIWYG will depend on the features of your XML authoring software. We use Syntext Serna as it has good support for WYSIWYG and inline editing of XML #includes (no-one else seems to support the latter). You may find other XML authoring tools better suit your needs - Serna is an reasonably pricey commercial offering.

Docbook provides a lot of flexibility via profiling, which allows you to include/exclude xml elements based on their attributes. Example use cases would be to have slightly different help output for OS=Windows than OS=Linux. Localization is also supported via profiling and other mechanisms.

A fairly good introduction to Docbook can be found here.

We use Docbook for our help format, and compile it to CHM files that contain help only for the features relevant to a specific product (ie Enterprise edition has features that aren't in the Standard or Demo versions). The relevant steps are:

1. Run the Profiling XSL templates on the XML Source (using eg XSLTproc).
2. Run the HTML-Help XSL templates on the output of 1.
3. Compile the output HTML files using Microsoft's HTML Help Compiler (HHC).