B Y   N E I L    P E R L I N
Boston Chapter

This column previously appeared in Accelepoint, from Clear Point Consultants.

Once upon a time, technical communication was a simple world. After you learned Word or Interleaf TPS, your professional toolkit was complete and you could spend your time learning the subject of your latest project and writing about it. In other words, writers were writers.

That world vanished with the coming of WinHelp and HTML. The material still had to be written but the technical aspect of technical communications began to dominate. Today, writers deal with issues like "help" vs. "user assistance", markup language compatibility, knowledge management, and repurposing. Many of these areas are new and ill-defined, but some will revolutionize technical communications just as word-processing did twenty years ago.

This column deals with a common problem in electronic documentation - sound-alike or confusing formats such as Web help vs. WebHelp, HTML Help vs. HTML help, and "compiled HTML" vs. "uncompiled HTML Help".

We're swamped by formats whose names sound similar but whose features and technical requirements are anything but. For example, are Web Help and WebHelp two different formats or simply a typo? It sounds like a silly question but it's crucial. Consider the consequences of getting it wrong - selecting the wrong format; buying the wrong authoring tool or using the right tool the wrong way; hiring people with the wrong backgrounds; generally wasting time, money, and resources. Some real-life examples:

• One group created HTML Help but couldn't understand why their help system didn't have Contents, Index, and Search tabs like other help systems. The problem? They interpreted the words "HTML Help" as meaning "a web page containing help contents" rather than as "the Microsoft help format".
  
  
• One manager saw "WebHelp" in a proposal, assumed it was a typo, and changed it to "Web help".
  
  
• Two developers got confused by the term "uncompiled HTML Help" in relation to WebHelp. As they said, "HTML help isn't compiled in the first place..." The problem? Misunderstanding the difference between HTML-based help and HTML Help and confusion over the compilation issue.
• Two developers were unsure what version of IE users needed in order to run the finished RoboHelp HTML 2000 file, and which files to distribute. The problem? They were confusing RoboHelp, the authoring tool, with HTML Help, the file format produced by the authoring tool.

These people got tangled up in terminology, a problem that will only get worse as new formats appear. Some suggestions:

• Be sure you understand current formats and are at least acquainted with trends.
  
  
• Never leave a project meeting until:
  • You're absolutely sure what the client wants. Clients often request the latest hot acronym without understanding what it is.
    
    
  • The client is absolutely sure what you're going to create. If necessary, spell it out. Literally. Say "HT - as in Thomas - ML" or "HD - as in Dog - ML".
    
    
• Be prepared to educate the client. Some will get annoyed - "Why do I need to know this? That's your job." - but better to have an annoyed client now than a furious one later after the project has gone bad.

Let's now turn to the actual formats. This column covers HTML Help, the "third-party" formats, and Java-based formats. In the next column, I'll cover the web as a medium for help, some new markup languages, authoring tool issues, and new design concepts like user assistance and embedding.

One of the first things you'll see about HTML Help is its obvious WinHelp ancestry. Figure 1 shows the major panes from a WinHelp file. Figure 2 shows a basic HTML Help file.

Figure 1 - WinHelp Figure 2 - HTML Help

Both formats have a topic pane and a tabs pane with Contents, Index, and Find/Search tabs. (The attaching or "docking" of the tabs pane to the topic pane in HTML Help fixes a WinHelp usability issue, the closing of the tabs pane when users open a topic.) This similarity makes it easy for users to switch from WinHelp to HTML Help. But there are two major differences.

• HTML Help is based on HTML, not on RTF like WinHelp. Microsoft owns RTF but never saw much revenue from it and thus had no incentive to debug or extend it. HTML is an open format so there's a lot of incentive to debug and extend it. This means HTML Help should advance faster than WinHelp.
  
  
• HTML Help uses "compiled HTML". This means that an HTML Help project may have 500 topics in 500 separate HTM files, like a Web site, but those 500 HTM files are compiled, or bundled into, one distributable file, like WinHelp. In WinHelp, the main distributable file is the HLP; in HTML Help, the only distributable file is the CHM.

Compilation offer benefits like easier file control and better searching, but causes two problems.

• HTML Help requires a specific configuration on the users' PCs - Windows 95, 98, NT 4, or 2000; the HTML Help viewer; and IE 3.02+. Mac and Unix users, and Netscape users, can't use HTML Help.
  
  
• The "compilation" causes problems when running HTML Help from a server. Unlike a Web site where each topic is a separate HTM file that gets sent individually to a user's PC, the entire HTML Help file gets sent. Network performance may suffer and the idea of centralized maintenance gets lost.

These two problems may make HTML Help unsuitable for you. If so, you may have to use a third-party format like WebHelp or InterHelp.

The major third-party formats are Blue Sky's WebHelp and Forefront's InterHelp. These formats are often called "uncompiled HTML Help" and are a cross between a Web site and HTML Help. They mix the Web site's browser and platform independence with HTML Help's navigational consistency. What does this mean?

The benefit of a Web site is that almost any browser can display it. The drawback is that every Web site has a different navigational model. This variety is fine in Web sites but a problem in help systems, where users don't want navigational elegance; they just want a fast answer to a question. Look at the sites in Figures 3 and 4. Both have completely different navigational features.

Compare these navigational variations with the basic HTML Help format in Figure 5.

Figure 5 - HTML Help

If help developers use HTML Help's default tri-pane look, every help system gets the same navigation tabs in the same place and sequence. Users who know how to use one system can use any system. So HTML Help is more consistently usable for help than a Web site. The problem is its configuration requirements - Windows 95, 98, NT 4, or 2000; the HTML Help viewer; and IE. That's where the third-party formats come in.

These formats are "uncompiled HTML Help". They're basically Web sites with extra control files that add navigational features similar to those in HTML Help. Compare WebHelp and InterHelp, in Figures 6 and 7, with the HTML Help look in Figure 5. (The term "uncompiled HTML Help" is often confusing. "If it's uncompiled, how can it be HTML Help to begin with?" Define this term when using it with clients.)

Each format resembles HTML Help but without the configuration requirements and server problem. The vendors claim these formats will run under version 3 of Netscape and IE, and under Windows 3.1, the Mac, and various versions of Unix including Solaris, HP UX, and Linux. So why not adopt one of these formats and avoid HTML Help entirely?

• The third-party formats are proprietary to specific help authoring tool vendors - WebHelp to Blue Sky Software and InterHelp to Forefront. This raises several problems.
  
  
  • Your selection of a third-party format is more likely to be based on which authoring tool you use than on which third-party format is necessarily the best for you.
    
    
  • Different third-party formats don't necessarily support the same HTML Help features. This means that converting from one format to another, if you convert from one authoring tool to another, may require some redesign of your help.
    
    
• You want to create one of the third-party formats, but the authoring tools are oriented towards creating HTML Help which then gets converted to the third-party format. Those formats don't support all the features of HTML Help. Therefore, you have to remember to design for the format rather than for the immediately available HTML Help features.

The Java-based formats are optimized for providing help for Java applications and applets and actually use HTML as the coding language. There are two formats in this group.

Sun's JavaHelp is the standard. Based on HTML 3.2, XML, and 100% Pure Java ( technology, it can run on any platform that supports the Java Runtime Environment (JRE). Figure 8 shows a simple example of JavaHelp 1, created by converting an HTML Help file to JavaHelp using the ForeHelp help authoring tool.

Figure 8 - JavaHelp 1.0

Oracle Help for Java (OHJ) began as an independent format when Oracle decided Sun was taking too long to release JavaHelp. Once the JavaHelp standard firmed up, Oracle adopted an extended version of JavaHelp in late 1998.

The Java-based formats have two major benefits. They're largely platform and browser independent, like the third-party formats. They're also optimized for Java applications and applets.

Unfortunately, the Java-based formats also have some problems.

• They're slower than their WinHelp and HTML-based equivalents. This is a Java problem rather than a JavaHelp problem but the speed difference is very noticeable to anyone coming over from Windows.
  
  
• The technical environment is new and unfamiliar, especially for developers coming from Windows or HTML. You'll need to learn about the Java Runtime Environment (JRE) and the Java Development Kit (JDK), applications vs. applets, and Virtual Machines (VMs), among others new concepts.
  
  
• Two business issues may affect your evaluation of JavaHelp. One is the issue of copyright as Sun tries to come to an arrangement with a third-party standards group. The other is Sun's lawsuit against Microsoft and how that might affect your help systems.
  
  
• At this time, only JavaHelp is supported by the major help authoring tools - RoboHelp and ForeHelp. Oracle Help is not, so you're much more on your own.

That's it for now. In the next column, I'll discuss the web as a medium for help, some confusing new markup languages, authoring tool issues, and new designs like user assistance and embedding.

Neil Perlin has twenty-one years experience in technical writing, with fifteen in training, consulting, and development for various types of online documentation including WinHelp, HTML Help, and some now known only in legend. Neil writes about online documentation and is a popular speaker before the STC and other professional groups. Neil provides training, consulting, and development for online documentation through Hyper/Word Services of Tewksbury, MA. You can reach him at nperlin@concentric.net or www.hyperword.com.

Copyright © 2000 Neil Perlin submitted to the STC for use in Hyperviews:Online.