Product ReviewTop-Notch Help AuthoringRoboHELP Office 2000

• By Lowell Thomas
• August 14, 2000

When we learned that Java Report reviewer Lowell Thomas was working on a Help system for an e-commerce company in Chicago, where he does the bulk of his consulting work, and that he was using one of the leading Help authoring tools with a JavaHelp feature, we asked him to give us the lowdown.

Lowell writes:

The [development] objective has long been seen in the simple and narrow terms of getting the application working and out the door as quickly as possible. In the best case, developing good documentation was seen as significant, but of secondary or even tertiary importance (behind perhaps QA/Testing). Often, it was little more than an afterthought. Software professionals have begun to see the error of their ways, usually through the painful experience of having an otherwise good application fail to reach its potential because users just couldn't figure out how to get around it effectively and efficiently. In light of current robust development practices and methodologies, many software makers now realize that an effective Help system is not an accessory to an application, but a crucial component of a modern software system.

—John K. Waters
Product Review Editor

Version Reviewed: 2000 Current Version: 2000
CUP RATING SYSTEM: 5 Outstanding 4 Very Good 3 Acceptable 2 Has Potential 1 Poor

I RECENTLY TEAMED up with a group of developers who had built a product procurement desktop application that was ready to deploy on the Windows NT desktop, but which had only a rudimentary Web interface still in development. C++/COM was used to create the desktop app, and the intention was to roll out a Web-based version using a combination of HTML, JavaScript, and COM.

My task was to create both comprehensive, context-sensitive, online Help for the NT desktop application and to construct a limited Web version of the Help system (Web pages posted on the extranet accessible to users of both major fourth generation browsers), aimed at developers making use of the SDK. Since the application was in relatively early stages of development, and therefore needed to go through several more builds, an important aspect of the SDK documentation requirement was to allow for content that could be dynamically updated into the Help system as the developers went through each build cycle. An ActiveX database control would be employed to encapsulate the content so that the text of each SDK component could be linked directly from the developer source builds into the associated Help topic.

Many of you have no doubt come across project requirements similar to what I've just described. Although the details may differ, the mission is the same: Create a Help system targeted to deploy in multiple ways, including as a stand-alone component of a desktop application, as part of a Web-based application, as an Internet/intranet/extranet Web site, and as printed documentation. Such Help systems are becoming increasingly common in the rapidly evolving global e-commerce environment, where companies are leveraging the Internet and the desktop to conduct their business transactions. Today's developers of Help systems need sophisticated tools to facilitate the rapid development and deployment of such systems.

RoboHELP
eHelp Corp., formerly known as Blue Sky Software, has had RoboHELP Office 2000, its flagship Help authoring system, on the market for several months now. I chose RoboHELP for this project because (a) it has a reputation throughout the authoring community as a top-notch tool and (b) I needed a solution that would allow me to get productive in as short a time as possible.

Up and Running
Setting up RoboHELP Office 2000 on Windows is a very straightforward process. I installed the software on both my Windows 98 system at home and a Windows NT 4.0 machine at the client site. Both installs went off flawlessly: I just popped in the CD and followed the install instructions. No surprises whatsoever. The only choice you have to make is the directory on your hard drive or network where you want the files to reside. The technical requirements are the usual for a 32-bit Window application (although 16-bit installs are allowed). On top of that, you need Word 95, 97, or 2000 preinstalled on your machine. RoboHELP takes up about 64 MB on your hard drive, but you'll need about 98 MB free for the full install.

Performance of this product is directly proportional to the amount of memory you have on your system (of course), so you'll want plenty of RAM, and a big hard drive is preferable. Both of the systems on which I installed it had upwards of 192 MB RAM and 15 GB of free space—performance was never an issue. See Figures 1 and 2 for screen shots of the respective interfaces.

Figure 1. RoboHELP Office 2000 HTML.

Figure 2. RoboHELP Office 2000 classic.

Once the product is installed, you should have access to the following components on your desktop and from the Windows Start menu:

• RoboHELP Classic
• RoboHELP HTML
• RoboHELP Office Tools
• eHelp.com (the online eHelp community)
• Getting Started with RoboHELP Office (the stand-alone Help tutorial)

At start-up of either program, you get the option of opening an existing project or creating a new one. Being true to the concept of providing good user assistance to the end user, RoboHELP Office comes with a couple of sample projects to get you started. You can also refer to the Getting Started stand-alone Help tutorial for a quick overview of the system. If you choose to create a new project, you are provided with several template projects to choose from. The available templates depend on whether you're using the RoboHELP Classic or the RoboHELP HTML interfaces. The range of templates provided includes Application Help, Stand-alone Help (WinHelp or HTML Help), What's This? Help, Online Books, and slide presentations. RoboHELP also allows you to create your own custom templates based on style sheets of your own creation that can be added to the New Project menu, or to easily import Help projects created in other authoring environments, such as ForeHelp and Doc-To-Help.

RoboHELP Office 2000 has a pretty good project organization metaphor. Whether you're using the HTML or the Word interfaces, there's a Window situated on the left side of the screen called the RoboHELP Explorer. Following the Windows explorer or standard tree view metaphor, you can browse through each category of project components or folders. These categories differ somewhat depending on whether you're using the RoboHELP HTML or Classic/Word interface but break down roughly into topics, images, multimedia, styles, build tags, and baggage (including XML and JavaScript files). The RoboHELP Classic interface gives you a finer directory structure to categorize the project elements. It offers under the topics folder, for instance, the additional subcategories: external topics, broken links, and duplicate topics; and under a project folder: Windows Map/Context Ids and Startup macros; and other folders to organize dependencies such as DLLs, external Help files, and URLs.

In either interface, on the bottom of the Explore pane there are three or four other tabs: TOC, Index, Glossaries (HTML interface only), and Tools. The TOC tab gives you a view of the project's table of contents. In addition to going directly into a wizard that automatically generates the table of contents for your project, by right clicking in this space you can add new elements, search for existing topics, and otherwise gain instant access to features that allow you to edit and organize your topics. Similarly, the Index and Glossaries tabs allow you to auto-generate an index and glossary for your Help project.

Extra Tools
The RoboHELP Office 2000 Tools consists of several items that can make your life easier, especially when it comes to leveraging existing Help systems. These include Help-to-Source, which converts Windows Help (.HLP) files into .RTF and .HPJ source files; WinHelp Inspector, which allows you to scrutinize Help systems for DLLs, topics, macros, and the like; and HTML Help Studio, which gives you the ability to decompile Microsoft HTML Help files and extract the elements into your project. There are tools such as the PC HelpDesk, which allows you to integrate a Help Desk ODBC database into your Help system; a What's This? Help Composer, which scans your VB or C++ application and automatically creates a context-sensitive Help project; and various graphics tools.

Other tools you have access to from the menu within the Explorer pane let you control when macros start, add and remove map ID references for context sensitive Help, and generate a wide range of reports. These reports include project status reports, which give an overview of the progress of the Help project (especially useful when you have a team of people working on a system); diagnostic reports that summarize the topics in your project and reference all those topics with unassigned map IDs; and various reports on referenced and unreferenced topics, used and unused files, etc. Figure 3 shows a typical RoboHelp report.

Figure 3. Typical report.

Moreover, you have access to other tools such as the Software Video Camera, Graphics Locator, and ReSize Help to help you manage all the graphical components of your project. Also included in the box is a copy of PhotoShop LE (which has all the graphics editing functionality you'll need). Although the Software Video Camera is a useful tool for capturing videos of screen actions, it didn't work when I first tried it out, and I had to reinstall some components to get it going.

Overall, I found the graphics toolkit to be a bit weak. eHelp could have done a better job of integrating screen capturing into the main interfaces, because as it stands, you'll have to go elsewhere just to do your static screen captures (unless of course, you're satisfied with Ctrl + Print Screen). One of the other Help authoring environments I looked at was EC Software's Help & Manual. It provides significantly more intuitive interfaces for doing graphics captures, and it eliminates the need to bounce from tool to tool (as I did with RoboHELP) to compose and organize all the graphics in a Help project.

Single Source Projects
All RoboHELP Office 2000 projects follow the single-source paradigm. This paradigm gives you one view of the project and has the ability to generate source files associated with any of the available formats, including WinHelp 3, WinHelp 4, WebHelp 3, Microsoft HTML-based Help, Windows CE Help, Netscape NetHelp 1.0 or 2.0, JavaHelp, and printed documentation. Although it's not unique to RoboHELP, this powerful feature means that you don't have to maintain a separate project and source file for every Help system you build from common elements. In the RoboHELP Classic interface, you can easily access this feature from the main project Explorer pane, and deploy to all available targets. When you're ready to generate your Help system, just open the single-source folder and select the target format from the list. From RoboHELP HTML, go to the File menu and select Generate to deploy to slightly more limited sets of targets, including Microsoft HTML Help, JavaHelp, WebHelp, or printed documentation.

Troubleshooting and Testing
RoboHELP Office 2000 provides a number of tools that aid in testing your Help projects. Authors can readily click the ActiveTest button from the toolbar to check for errors in their topics on the fly, without having to compile. You can enter Link view to see all your topics (internal or external) in a graphical manner, giving you the ability to test various types of hotspots (pop-up, HTML macro, jump, image, etc.), broken links, and navigate browse sequences. An integrated BugHunter comes with the RoboHELP Office HTML. This feature gives you instant feedback on your context-sensitive HTML or JavaHelp projects by intercepting calls directly from the application using the Help system. It also reports on specific command calls, topics, and map IDs, and it logs the results to a window located at the bottom of the interface.

There's also a BugHunter feature in the RoboHELP Office 2000 Classic interface, but you access it as a separate app from the Tools pane of the project Explorer. Its functionality is similar, but here the focus is on fixing problems specific to creating context-sensitive Help for Windows applications, so it's aimed at intercepting Win API calls needed to work with WinHELP projects. For performing compile-time error checking, the RoboHELP Office 2000 Classic interface has an Error Wizard. This wizard goes well beyond just logging compilation errors; it locates the topic causing the error and actually provides explanations of what the error means, as well as suggestions for correcting the problem.

And, as I mentioned earlier, a wide range of reports are available, from diagnostics that capture things such as missing images, DLLs, and duplicate or unused map IDs (which you can run prior to compile time) to reports on unreferenced topics, tables of contents, and indexes. All in all, the tools offered by RoboHELP for diagnosing and fixing problems are top-notch. They're one of the reasons the product continues to be one of the dominant Help authoring platforms on the market today.

Conclusion
eHelp's RoboHELP has long enjoyed a reputation as the premier Help authoring tool. After putting the company's Office 2000 suite to the test myself, I found that it deserves its reputation. I was able to knock off the project within a few weeks with this powerful tool. All the requirements I faced—from building the online Help for a large and complex C++ application, to integrating a custom ActiveX database control and getting a cross-browser-accessible Web site up and running (via WebHELP)—I was able to deliver on time and within budget using RoboHELP.

Learning the tool's intricacies will take a little time, but there's a great deal of documentation built into the system that should make that task a simple and straightforward one.

Keep in mind that although the RoboHELP interface is highly sophisticated and feature rich, it is somewhat unwieldy. I wouldn't call it a major drawback, because the tool is so powerful and because, once you get the hang of it, you can accomplish just about anything you need with ease.

Another thing I didn't love about the product was its dependence on Microsoft Word. Though you have the option to work entirely in the HTML WYSIWYG environment, the Classic interface has more features than the HTML environment and must be used to create Windows application Help. But these are relatively minor quibbles. Many developers are quite comfortable working in Word as a primary document production tool, and adjusting to Word-mediated Help authoring isn't much of a stretch.

Overall, I found the tool to be very powerful and an excellent choice for Help authors looking for a comprehensive environment to develop a wide range of Help systems.

VENDOR INFO
eHelp Corp.
7777 Fay Avenue
La Jolla, CA 92037
800.677.4946
www.ehelp.com