If there is one thing that developers and users always seem to disagree on, it is the relative importance of documentation. We take a look at the whole technology of producing Help and Documentation for tools and applications, and then review one particular product; EC Software's Help & Manual

A HAT (Help Authoring Tool) is a specialised development tool for creating documentation and Help for applications. Unlike normal document formats, Help documents must provide the means to hyperlink to the relevant information from any part of the application for which it is providing the help, and provide easy access to answers via good search, indexing and chaptering. Nowadays, it must do so via a number of different media.

In this article, we will review one particular HAT, Help & Manual, but we'll try to explain a bit about Help Authoring in general too, for the developer who is also required to get involved with the production of application help

Documentation and IT Applications

... and provide easy access to answers
via good search, indexing and chaptering.

For the end user, it doesn't mat­ter how well an app­lic­ation has been wri­tten if the help and doc­ument­ation is poor.

In the hot­house, geeky cul­ture of an IT dev­elop­ment team, the way an app­lic­ation works must seem ob­vious. In the real world out­side it often isn't, but well-crafted help and doc­ument­ation can ease the cult­ural gap re­mark­ably well.

The Tech­nical Au­thor is gen­er­ally resp­ons­ible for the Help Text, the print­ed manual, the 'white papers' and the mat­erial on the web­site. It is a daunt­ing task. In­creas­ing­ly, the work has to be sent to a bureau for trans­lat­ion into other lan­gua­ges; and the cont­ent has to survive trans­lat­ion into wri­tten lang­uages that go from right-to-left, or ver­tic­ally, as well as left-to-right. There may still be a dem­and for the pro­duc­tion of a prin­ted man­ual or PDF file too.

To make the task poss­ible, tech­nical con­tent must have a single source that can cater for all these de­mands. This is where a HAT (Help Author­ing Tool) comes in, and any tech­nical author who works with Win­dows app­lic­ations will be fa­mil­iar with HAT software.

A HAT allows the writer to create a single source text, which it can then convert to a number of target formats. This is known as Single-Source publishing. Usually, the author creates the source text using a built-in editor. The production of a Windows Help file is usually still the most important task, though WebHelp is becoming increasingly dominant.. Windows applications that use the windows Help APIs require the development of a compiled Help file in a format such as WinHelp (*.HLP) or Microsoft Compiled HTML (*.CHM). However, it is no longer enough; HAT applications are expected to be able to output in all the formats and media types that are used for documentation, so that the technical author can manage the documentation from a single source and with a single tool. Increasingly, too, documentation is translated into a number of languages: a European application can scarcely escape with less than five language versions. A HAT must be able to accommodate this.

The emergence of Help-Authoring

As soon as Windows materialised, there were APIs defined in Windows to allow applications to link directly to sections of text within a help file. Hyperlinking was first introduced as a specialised technique for Help Authoring, long before the Internet. Word processors couldn't do hyperlinking, Microsoft's tools for creating Help Text were primitive, and so a gap in the market emerged.

HATs originally developed from two types of application:

1. Those that took the source text from a file produced by another program (as in DocToHelp)
2. Those that allowed the author to create the text and layout within the tool, by itself.

After a while, the distinction became blurred, and all major systems now allow importing from a range of formats such as ASCII, HTML and Microsoft Word. This imported text can then be edited, formatted and 'hypertexted'. The output can be a compiled Help file in a format such as WinHelp (*.HLP) or Microsoft Compiled HTML (*.CHM), but can also be in a conventional file format such as Adobe PDF, XML or HTML. Microsoft Help 2.0 / Visual Studio Help, Rich Text Format (RTF) and eBooks (Windows executable containing an embedded viewer). They generally have facilities for the printing of manuals too. Some systems, such as RoboHelp, also can output help in FlashHelp, Sun JavaHelp and Oracle Help for Java

The early Windows-based Help Authoring Tools were pretty primitive, but effective. DocToHelp was one of the first. It was originally nothing much more than a set of macros that ran in Word and converted the Word document into something that could then be compiled by the Microsoft Help compiler. It has come a long way since.

RoboHelp was a pioneering system that was one of the first to be especially built as a stand-alone application. It remained the market leader until an unfortunate set of changes in ownership (Blue Sky, to Ehelp, to Macromedia Corporation, to Adobe) led to it being sidelined for a while, during which time the chief developers started a breakaway concern, Madcap Flare. But poor RoboHelp wasn't dead yet. RoboHelp 7 recently popped out of the Adobe woodwork, with Unicode support, Vista and Office 2007 support, a more flexible user interface and cleaner editor.

Various HAT systems

Over the years, a whole range of tools and applications have been developed to ease the work of the Technical author in producing Help text. They vary from the corporate database-driven multi-user applications to simple utilities to convert marked-up text to a help file. Some have developed as add-ons to publishing systems, others from word processor add-ins. Here are some of the better-known products:.They generally provide the basic functionality of providing tables of Contents (TOC), indexes, and the incorporation of other media such as Flash and Video. Many of them allow conditional processing depending on the output media or version of the application (e.g. 'Pro' or 'Lite'), and the inclusion of external files at compile time. The flagship products provide multi-author systems with version control, rollback and change-tracking.

AurigaDoc

(AurigaLogic). AurigaDoc is a java-xml-xsl based documentation tool for writing xml documents and converting them to other open formats like HTML(single and multi page), DHTML, PDF, PostScript, Formatting Object(FO), RTF, Java Help and HTML Help(.chm). (It is not an xml editor).

AuthorIT Enterprise

(AuthorIT Software) A database-driven collaborative authoring tool for large team-based projects.

CHM Converter

(ABC Amber) CHM Converter is a batch decompiler for Compiled Windows HTML Help it will convert CHM files or CHM ebooks to any document format.

chm2web:

Help authoring solution for creating customizable webhelp.

Doc-To-Help

(ComponentOne) One of the earliest systems, now a specialized tool for creating online Help and printed documents.

Doc-O-Matic

(toolsfactory GbR) for large online documentation system creation. Creates cross-linked documentation systems, including source code documentation, online help and user manuals in all the standard formats.

Extreme Ease

(HelpConsole 2007 ) A help system designed particularly for the production of browser-based help or WebHelp

Flare

(MadCap) . Flare is based on RoboHelp and is marketed as a replacement. Madcap tools are all based on XML.

HelpServer

(4ST) A Multiplatform, web-based HAT for help and documentation throughout an enterprise, which can be used both as a content management system and as a help system. It is equipped with an authoring tool.

Help Explorer

(HelpExplorer Software) Help Explorer Server is a web-based application designed for viewing compiled help files in different formats. Help Explorer Server provides online access to any kind of help resources.

Help Generator

(AGORA Software BV/4TOPS) This scans the application and automatically generates HTML files, screenshots and other elements needed to make the help file and user documentation. It also links the help topics to the appropriate application forms automatically, to provide context sensitive help. Includes a Help Editor

Help & Manual

(EC Software) The subject of this review

HelpMaker

(Vizacc) Free WYSIWYG help authoring tool the outputs in WinHelp, HTML Help, PDF and other formats.

HelpStudio

(Innovasys) A .NET Help authoring application with all the usual features, but featuring HTML Widgets that deliver dynamic content (e.g. drop down sections, enlarge in place images, colorized example code) without any manual authoring effort or specialised knowledge. Innovaysys also produce Document X

HyperText Studio:

(Oslon Software) WYSIWYG Help authoring tool for creating WinHelp, HTML Help, browser-based Help and print documents.

PaperKiller:

(VisualVision) Cheap, visual WYSIWYG Help authoring tool for creating WinHelp, HTML Help and CD/DVD based help and manuals

RoboHelp

(Blue Sky, then Ehelp, then Macromedia, then Adobe) A specialized tool for creating online Help. One of the first comprehensive Help tools, recently revived by Adobe in a competitive form.

WebWorks

(Quandralay) WebWorks Publisher works with Adobe FrameMaker to convert FrameMaker documents to online formats, including Web formats (DITA, HTML, HTML + CSS, XML, XML + CSS, XML + XSL), as well as online Help formats (WinHelp, HTML Help, JavaHelp, and WebWorks Help).

Authoring Utilities

As well as a HAT, and some utilities for repetitive chores, there are some useful authoring tools out there for the technical author

XML Editor This is a very handy XML editor that can edit a number of XML formats including DITA, DocBook 4 / DocBook 5, TEI P4 / TEI P5 and XHTML.

TopStyle

(BradSoft) The best CSS editor, and excellent for creating well-formatted HTML documents

CHM Editor

(GridinSoft) A WYSIWYG editor that can be used for editing and translating CHM files.

helpware.net

(FAR) Utilities for help authors and developers in managing Help files. Intelligent Find and Replace, CHM link checker; TOC and Index editors; CHM comparison and extraction tools; Web to HTML Help wizards, and tools for doing Microsoft's MSI Registration, without using MSI (Microsoft Installer).

HAT Output formats

... there are now a whole range of
text-based media
 

The software industry is consistently increasing the ways that it presents documentation to the end user. Whereas WinHelp was once sufficient, there are now a whole range of text-based media, including web-based versions. Also, it is usual for the printed documentation to be produced from the same source. Video presentations, demonstrations and walk-throughs are now common

HTML Help

For the Windows developer, the most important output format of all is usually Windows HTML Help. This is now the standard help system for the Windows platform. It uses a Help viewer (which uses the underlying components of IE), rather than just the browser itself. The Help viewer is able to view a single file (.CHM) which compresses the HTML, graphic, and other files into a relatively small compiled help file.

The HTML Help compiler also provides a combined table of contents and index, as well as keywords for advanced hyperlinking. From code, the application developer can provide context-sensitive help from within the help file by using the Windows Help API.

As well as creating the online help for a software application, or even content for a Web site, Windows HTML Help can also be used for training guides, interactive books, and electronic newsletters.

WinHelp

WinHelp is a proprietary format, based on Rich Text Format (RTF), which can be displayed onscreen by winhelp.exe or winhlp32.exe and was current from Windows 3.0 platform through to Windows XP. It is no longer available in Vista

A WinHelp file has a ".hlp" suffix. It can be accompanied by an optional table of contents (.cnt) file if the help developer created one. When Windows opens a WinHelp file, it creates a .gid file in the same directory, containing information about the .hlp file such as the window size and location. If the user clicks the "Find" tab and enables keyword indexing, Windows creates an index file with a .fts (full text search) extension.

A WinHelp file is compiled from various source documents (HPJ-(project file), CNT- (table of contents), RTF (rich text), BMP (images), SHG (Image map of help calls for a graphic file).

Microsoft Help 2

This was once planned as a successor to WinHelp, but never made it. It is often referred to a Visual Studio Help. It has a ".hxs" extension and is compiled from a range of files that include a set of topic pages written in a subset of HTML as well as a project file, Table of Contents file and various index files

Originally, this format was released only for the help system used by Visual Studio .NET 2002, MSDN Library and TechNet; The advantage of using Help 2 is that the documentation becomes part of the VS.NET's own documentation, making it possible to provide context-sensitive help for third-party VS.NET components. It will never be released now as a general help format but Microsoft ware still actively supporting the format and it is used by a number of third-party IDEs as well

Ebooks

There is, unfortunately, no single format for producing an Ebook. There are a host of alternatives (See the Wikipedia entry). Help & Manual provides yet another Ebook file format. Luckily, it is very similar to HTML Help and runs immediately with its own built-in viewer. Files can be Password protected and the books can be given a number of different layouts and appearances.

XML-based help

XML is useful, but there is no XML standard for documentation. The closest we get is probably the Darwin Information Typing Architecture (DITA) XML standard for technical documentation. DocBook is an ingenious XML-based system, which enables its users to create documents in an output-neutral form that captures just the logical structure of the content; This can then be published in a variety of formats, including HTML, PDF, man pages and HTML Help, without any changes to the source.

There is a very useful method of using and extracting XML comments from C# source files in Visual Studio and exporting to NDOC (which does not support .NET 2.0), or SandCastle. (see 'XML Documentation Comments Guide' ). Steve McCabe's excellent SQLTac will export SQL Server database documentation as XML.This is an excellent way of documenting APIs, which may eventually get into the technical documentation for the end users.

An interesting issue is how to import help information into databases. In many applications, text will be produced directly from the database, particularly where a user error is triggered. This has to be in the current language selected for the application. XML-based help is ideal for this, and can be easily imported from the project source documentation whenever this is changed, or a new translation is created.

PDF

PDF was originally developed as a document interchange format. However, it is the only way of distributing documents with a clearly-defined layout and formatting that do not change on different systems. It is suitable for downloading but not for online viewing, but it excels as a delivery mechanism for printing. It is proprietary, but there are moves to create an open standard; ISO 32000.

Adobe PDF files look exactly like the original documents from which they were created and preserve text, drawings, 3D, full-colour graphics, photos, can be viewed on all platforms and can easily be searched. It is possible to hyperlink to bookmarks, or pages from an external application, in order to provide help and documentation, using an approach very similar to HTML. However, users must always download the entire document, even if they only want to view a single page.

WebHelp

Webhelp was originally a term coined by the creators of RoboHelp to describe Help delivery via the browser. WebHelp enables browser-independent, platform-independent online Help and electronic books using a combination of HTML, DHTML, JavaScript, Java, and ActiveX. The ideas have since been developed greatly and now underpin MSDN. HAT systems such as RoboHelp, Flare, Help Explorer and Help & Manual all provide such a system. At the moment, it looks as if WebHelp is likely to dominate as a means of providing help to applications, but implementation is made more complex by the problems of providing help in places without internet connection. There are several advantages to server-based WebHelp, One can gather information on the usage of pages (e,g, 'Most Popular Pages'), and use dynamic variables. One can also update the help content quickly, and provide new language translations much more easily.

Help & Manual - Top HAT?

Like many well-established tools, the best HAT applications vie with each other for features, and it would be fair to say that several of them have comparable facilities to Help & Manual. I generally use a rather old version of RoboHelp Office, and so it certainly surprised me, in looking at recent versions of Flare, Robohelp and others how far the breed had developed in the past few years. I must, however, admit to a soft spot for Help & Manual, because of the easy transition from Word as an authoring tool, the XML-integration, and its clever screenshot capture.

It wasn't initially Help and Manual that attracted me to EC software. It was TNT Screen Capture, their wonderful application for doing the screenshots of applications (Menus, windows, arbitrary areas of the screen) for documentation. It will add shadow, or give the appearance that the area has been torn from the application, or a range of other transformations of a plain screen-scrape. You can even add callouts.

Possibly the greatest difficulty in reviewing an application like this is that it takes time to realise that your existing tools are no longer necessary. So much of what is in Word or RoboHelp is already there in Help & Manual. Although the integration with Word is superb, it is much better to make use of the advanced features and do all the writing and editing in the application itself.

Help & Manual has the same sleek feel as Word. Everything has been thought out in a way that suits the job in hand. For example, the text, the user's settings for the project, and all the materials, are stored in a single file with an .HMX extension. When you start up the application, it feels just like a word processor. It also supports Unicode for creating help in all international languages, including Asian languages like Chinese, Japanese and Thai (but sadly not Arabic yet).

The program comes bundled with several tools, including:

• a screenshot capture tool (like TNT but simpler), with functions for editing and enhancing screenshots
• a help context tool for managing, importing and exporting help context numbers
• a "print manual designer" for creating and editing layout templates for PDF files and printed manuals,
• a reporting tool for generating and exporting project reports.

Multilingual issues

... or exported as an XML file.

Help & Manual really understands the issues of producing multilingual documentation. Perhaps this is hardly surprising in an Austrian company, based near Salzburg. Once the documentation is finished and signed off in its primary language, it can then be cloned, with one copy for each language, or exported as an XML file. These can be sent to the translation bureau. When the translations are completed, the various language versions can be re-synchronised from the master so that any subsequent additions or deletions in the structure of the document can be flagged for translation. It works, but it would be even neater to keep all translations within the master project.

Importing

Importing documentation is easy. Any .CHM and .HPJ files are imported exactly. Word documents get imported with every hard page break being treated as a topic division. Almost all the formatting is preserved, as well as the graphics and tables. Then, joy of joys, you can convert the inline formatting into proper style sheet formatting from within Help & Manual, and the graphics can be converted to external, rather than embedded, files. The application will maintain the structure of a Word file that is properly structured with Headings 1-9, so you end up with your table of contents reflecting your headings, structure and all.

HTML importing takes more practice. It will import an entire directory of material, with the table of contents reflecting the directory. It correctly interprets the hyperlinks and will even interpret the Metatags as indexes, but I found that it did not translate the formats of the text correctly from the CSS classes into the native styles.

Export formats

It is in the production of PDF and printed documents where Help & Manual presents us with a surprise. These are so good that one is left wondering if there is any residual use for Word. Naturally, the production of CHM and HLP files is faultless, but the addition of these other formats means that it is an easy decision to make Help & Manual the source of your application's documentation.

Browser-based help is a feature that will help a technical author to keep the website up-to-date with the latest documentation. It can be viewed by any modern browser and doesn't need the special viewer that the CHM format requires. It seems a handy way of doing all manner of technical web publishing, but it needs work on the directory tree, which is clumsier than it should be. An interesting facility is the option to pull in HTML pages at compile time, so that ephemeral information can be included in the build. This makes its use for technical websites an interesting possibility and it will be worth experimenting with this.

Conclusions

The distinctions between Desktop Publishing systems, Word processors, Help Authoring systems and Content Management systems is beginning to get very blurred.

Publishing Help files and publishing Internet sites are getting to be a very similar activities, since both use extensive hyperlinking, and both rely on HTML. There is a lot of convergence here. With the features of Help and Manual, you can create a very fine printed book, or a slick Information-based website, as well as conventional Help Text.

Like every other versatile system, the complexity of the Help & Manual system can be rather daunting but the help system is, unsurprisingly, excellent, and things work in a way that would be familiar to any user of Microsoft Word. There are clever ways of using DHTML to produce a range of effects, there are variables and macros, templates and modules, all of which are designed to increase the versatility of the application.

So, has the time come when a technical author can concentrate on using just one tool for producing all his output? We are certainly not far off.

EC Software are the publishers of Help & Manual and TNT Screen Capture