When I want to create a professional, well-organized HTML help file for my application, that provides a one-source stop for HTML help, a PDF User's Guide (which can be used for printing, of course), and context sensitive help for my application, I can get really tired of messy help file solutions like:
-
composing individual HTML pages and putting them together with Microsoft HTML Help Workshop, for which you have to have the help file layout
completely planned beforehand -- including the index -- only then to proof read it the next day and discover that certain topics need to be reordered, which, in my world,
should be something simple, yet it immediately invalidates about half a dozen links per page, or
-
less-messy-but-tedious solutions like taking screen-shots myself and composing my own set of callouts onto a graphic image that then gets incorporated into an HTML page, for each window of an application.
Ouch! That's a lot of time (days if not weeks), depending on the complexity of the application, and a lot of tedium, to get a clean, high-quality product.
Enter Dr.Explain
Dr.Explain is a help authoring tool that provides a simple user interface to create a wide variety of documentation, and automates many of the tedious tasks of doing so. Dr.Explain specializes in producing tree-structured HTML help, which can be output as:
-
compiled help -- a .CHM file, often used to provide general and context-sensitive help for applications on a wide variety of platforms (Windows, Mac, Linux, and others), and
-
on-line help in the form of a high-quality, coordinated set of HTML pages, which can be hosted on a website, complete with table of context, index, and full text search capabilities built in.
In addition, from the same source project, it enables the author to also generate:
-
a PDF file containing all of the HTML help content in sequence, with both bookmarks (tree-structure like a table of contents in a window usually on the left side of a displayed PDF document), and a table of contents with links to the specified pages, and
-
an RTF file, with a structure much the same as the PDF output, providing the ability to use it directly or import it into other tools for further processing.
One of Dr.Explain's Specialties
Although Dr.Explain is far from being limited to this use, it further specializes in documenting Windows software applications. It does this by providing a great deal of automation in many of the the tasks required to produce such documentation. Specifically:
-
capturing screenshots of the application,
-
automatically creating named and numbered callouts on top of those screenshots that call attention to specific parts of the application (panels, buttons, text boxes, dropdown lists -- in general most types of controls commonly used in Windows applications),
-
providing a means for easily editing the existing callouts, removing unneeded ones, or creating your own,
-
providing sections below those screenshots, one per numbered callout, in numerical sequence, in which to provide detailed descriptions of each callout item (you can re-number them in several different ways), and
-
placing all of these in a coordinated layout in a single HTML page ("topic" in HTML Help terms).
Example of Callouts Created Automatically by Dr.Explain
This is one place Dr.Explain really shines. This automation is a
dramatic production booster for Help Authors documenting Windows software applications. As a simple example, the commonly seen "Save As..." dialog box (depicted above) used by many applications contains 10 controls. If that was a
simple window in the application you were documenting, to document it would require the basic screenshot plus one named and numbered callout for each control, and one section in the page for each callout for a detailed description of that control. To do all this manually with a graphics application and manual HTML layout could easily require in the range of 60-90 minutes. Dr.Explain turns this into 5-10 minutes -- from beginning to end. See
Capturing Software Application Screenshots for details.
Providing a foundation under all this automation is the ability to extensively customize these pages, or develop your own independent HTML pages with a WYSIWYG editor which is as easy to use as any basic word processor, and provides most of the commonly-used layout capabilities of HTML, such as font control, text, hyperlinks, images, videos, ordered and un-ordered lists, and tables (if you are familiar with HTML, you'll already know how much power tables have, and Dr.Explain makes them quite versatile, enabling you to use a great deal of what HTML tables can provide, including the fact that cells can span multiple columns and/or multiple rows).
If you want to get really fancy, these capabilities include the ability to provide your own custom HTML code, custom CSS styles, as well as custom JavaScript.
Dr.Explain backs all this up with a well-designed method of:
-
easily managing the tree structure of your documentation (each node in the tree is a "topic" in HTML Help terms -- literally an HTML page when HTML help and/or on-line help files are generated)
-
automatically updating your table of contents so that it always matches this tree structure,
-
controlling which parts of the tree structure will be visible from the table of contents (it is sometimes desirable to make certain help topics only available from within an application, and not visible from the table of contents, or you may want to hide work in progress until it is ready to be released),
-
easily controlling which topics (HTML pages) will be output to which output formats (for example, certain topics can be output to PDF but not to HTML or vice versa)
-
tracking the status of each topic (Not Started, In Progress, Completed, Waiting),
-
and providing intuitive and efficient means of building an elaborate and full-featured 1-, 2- or 3-level index to help your readers easily find what they are looking for.
Dr.Explain further provides a number of useful facilities for managing documentation projects, such as variables, configurable text strings, customizable named text formatting styles (e.g. Normal, Heading 1, Heading 2, Code, Quote, add your own...), and the ability (if you want) to extensively
customize how screenshots are captured and annotated.
Finally, for each output format (CHM, HTML, PDF, RTF), Dr.Explain provides the ability to customize many aspects of the output layout pertinent to each format, such as page numbering, headers and footers, and other elements making up the visual appearance of the final documents.
