Help Generation Tools

Apr 01, 2008
by:   Tim Stanley

Help authoring tools like RoboHelp and Doc To Help provide the ability to generate PDF, Word .DOC, and compiled html help (.CHM) from a single HTML source.

Some time ago, I needed the ability to generate other forms of documentation for help files other than HTML.  The original content was authored as a standalone simple HTML (h1, h2, ul, ol, dd, dt, p, etc.) with images and used a common style sheet.  I needed the ability to generate other forms of documentation that could be printed and transmitted over the Internet to clients (Word documents, PDF, etc.). 

Requirements

The general requirement was for end user help for administration screens, not for programmer internal object or API help.  There are further tools that are more suited for generation of programmer API documentation (like Microsoft Sand Castle on the Codeplex Sand Castle site)

  1. Help documentation was originally written in HTML pages (standalone read from files, no ASP.NET or IIS Server)
  2. Generation and distribution of standalone PDF’s
  3. Generation and distribution of standalone .CHM (Microsoft Compiled Help)
  4. Generation and distribution of standalone HTML files viewable in Internet Explorer
  5. Generation and distribution of standalone Microsoft Word.doc files.
  6. HTML Used as primary Help and displayed in IE.
  7. Table of Contents written in HTML Pages
  8. Include HTML Images in all output (PDF, DOC, CHM) without requiring re-work.

Help Authoring Tools Evaluated

In evaluating the tools, I already had existing HTML documentation with images present.  If I were creating a new documentation solution from scratch, I might have chosen a different tool or approach.

The Microsoft HTML help compiler generates .CHM files from HTML, but it does not generate Word .DOC, or PDF formats so this didn't meet the requirements.  Both RoboHelp and Doc To Help utilize the help compiler to generate the .CHM files.

Doc To Help generated CHM files, PDF files and Word Documents, but generation of documents took a very long time (i.e. 20 minutes or more).  The output of the images in the PDF and Word Document was problematic.  I never could figure out how to generate the "contents" of those documents correctly.

RoboHelp generated the CHM files, PDF files and Word documents fairly quickly (less than 5 minutes).  The images were placed correctly, and with only minimal work I was able to generate the table of contents for all documents correctly.

Both tools provided the ability to edit HTML content, but this wasn't really utilized since all content was already in HTML format.   Both tools also provided the ability to utilize the existing CSS style information when it generated the documentation.

Robohelp was selected because it was significantly faster and had fewer errors in generating the required output than the Doc To Help product. Doc To Help would have required further investigation and “manipulation” of the original HTML source in order to generate .CHM or .DOC files without errors.   It's been used for several revisions of the documentation and it still works fine.

RoboHelp has also been a consistent Award Winning help generation product and has won the Best .NET Products of 2007 for Help Authoring.

Differences In Output

Why generate different output formats?  Each format has unique features that the other formats don't offer.  Some clients reviewing our documentation prefer one format over the other.  In particular, many clients prefer the ability to print the full set of documentation for review when evaluating the product.  Each format helps support the sales cycle as the circumstances dictate.  Printing in HTML and CHM formats is listed as poor because these formats only allow printing one page at a time.

Format Size in bytes View Search Print
HTML 15,398,787 Excellent Poor Poor
CHM 4,431,489 Good Excellent Poor
DOC 6,974,976 Excellent Average Excellent
PDF 3,538,957 Excellent Average Excellent

Sample Output

HTML Help sample viewed in Internet Explorer

Help HTML Employee Maint

PDF Help Sample Output from RoboHelp

Help PDF Employee Maint

Microsoft Word Sample output from RoboHelp

Help DOC Employee Maint

Compiled Help Sample output from RoboHelp

Help CHM Employee Maint

API Documentation Tools and Links

Add to favorites Send to a friend Digg It! DZone It! StumbleUpon Technorati Reddit Del.icio.us NewsVine Furl BlinkList