Friday, May 18, 2007

RoboHelp for Word or RoboHelp HTML?

When you buy RoboHelp, you actually get two separate modules – RoboHelp for Word and RoboHelp HTML. Which one should you use?

It seems obvious – use RoboHelp for Word if you write content in Word, and RoboHelp HTML if you write content in HTML. Simple, logical, and wrong. It’s a common error, and a great example of unintended consequences, in this case because of a product name change. What’s the problem?

The original RoboHelp was an add-on to Word and just called RoboHelp. When eHelp, the original vendor, released the HTML version in the late ‘90s, it had to distinguish between the two versions so it renamed them RoboHelp Classic and RoboHelp HTML.

This fixed the problem for a while. However, as more and more authors went directly to RoboHelp HTML, without ever using Classic, the word “Classic” became confusing. New authors didn’t understand what it referred to. To fix this, eHelp renamed RoboHelp Classic RoboHelp for Word. Unfortunately, this new name only made sense to authors who knew RoboHelp’s history. Authors who didn’t know the history made the mistake that I described above. So which module should you use?

RoboHelp for Word was designed to create the Windows Help, or “WinHelp” format that dates from the late ‘80s. Microsoft unofficially terminated WinHelp when it introduced HTML Help in ’97, but WinHelp remains widely used. However, it is declining quickly because of its technical limitations in the HTML/XML era and because of development headaches in the Word-based environment.

So unless you’re still creating WinHelp (and it’s time to be migrating to an HTML-based format if you are), you should not be using RoboHelp for Word. Instead, you should be using RoboHelp HTML. Here are three major reasons why:

More up-to-date – After Microsoft introduced HTML Help in ’97, it largely let WinHelp stagnate in its technology and its interface. The result is an output format that can’t take advantage of modern features and looks just plain outdated in our web-oriented world, unlike the HTML formats.

More efficient authoring – Many of the annoyances in RoboHelp for Word vanish when you move to RoboHelp HTML. Table handling is far better, with no more of the “Table cell borders not supported” errors, because HTML does a better job with tables than does Word. Topics are individual files, rather than combined in one huge Word file, so topic handling is more flexible. (Be warned, however, that you will lose some features that you take for granted, such as the non-scrolling topic titles and the button bar.)

Easier project maintenance – As HTML-based outputs have come to dominate the field in recent years, fewer and fewer authors know RoboHelp for Word. This means you may have a difficult time finding contractors or new writers who can maintain a RoboHelp for Word project.

But what if your subject matter expects write in Word? How do you use those documents with RoboHelp HTML? Not a problem; RoboHelp HTML can easily import a Word documents, automatically converting it to HTML and, in many cases, automatically breaking the Word document into a multitude of separate topic files.

In summary, if you’re not using RoboHelp’s HTML module, it’s time to think about it.

Note – I won’t be blogging again until the first week in June. Please check back then.

Wednesday, May 9, 2007

I’m preparing for the STC’s annual conference in Minneapolis next week (May 13-16), where I’ll be giving five presentations – a full presentation, a progression, two booth presentations on Flare for MadCap, and a Springboard.

The full presentation is called “It’s Not My Aunt’s Online Help Anymore”, a wonderful line that I borrowed from an attendee in a Flare course last fall. My focus is on changes in the technologies, methodologies, and business practices of online help, with specific suggestions on how to respond.

The progression is a comparison of the differences in features and design philosophies of Adobe Captivate and MadCap Mimic. (They both come out looking good. The choice depends largely on what kinds of movies you want to create.)

The booth presentations cover Flare’s Word import feature and its output customization features - e.g. how to create one help system but tailor it to multiple audiences.

The Springboard is a short (15 minute) discussion of why templates are good things for technical communicators and how to create and use them in Word, RoboHelp, and Flare.

If you’re going to attend the conference, I hope to see you in one of these sessions. If you won't be at the conference but are interested in any of the sessions, email me at
nperlin@nperlin.cnc.net and I’ll send you the Powerpoint slides.

Saturday, May 5, 2007

Responding to the comments about my May 2 post, with apologies for deviating from the low-gibberish quotient that I promised…

Re Tom’s point about formats supported by the DITA Open Source Toolkit and why WebHelp isn’t one of them - Officially, I don’t know. Unofficially, I’m pretty sure this is why…

Any authoring tool provider has to offer not only the tool itself but useful outputs as well. Without that, the tool is simply producing raw material. Converting that material to an output that can be distributed to users requires further processing, and that makes the tool less useful. So the answer is simple; make sure the tool can convert the material that it outputs to formats that can be distributed to end-users.

Every tool outputs HTML Help, for two reasons.

First, HTML Help, despite its age, is a standard. (It’s become an uncertain one and, in my experience, is in decline as people move to WebHelp, but it is still a standard.)

Second is a business issue. Tool providers can easily offer HTML Help because the “compiler,” the tool that turns the files in a project into a finished CHM, is part of a Microsoft tool called HTML Help Workshop that, I assume, Microsoft makes easy to license. And the “viewer” that runs the CHM has been built into Windows for years, so the authoring tool providers don’t have to do anything to make the CHM viewable on users’ PCs.

So all the authoring tool provider has to do is bundle HTML Help Workshop with the tool and add a few toolbar and menu options on the tool interface to launch the compiler and view the finished CHM. Easy…

(The same situation largely holds true for the older Windows Help and JavaHelp as well, which is one reason many tools offer them as well. Ignoring the fact that there are still companies using those formats, of course…)

In contrast, there’s no standard authoring engine for WebHelp. The idea of web-enabled output is the same no matter what the tool, but each tool provider has to create its own “WebHelp”. That means programming and expense. (They don’t have to worry about how to display WebHelp, however, since that’s taken care of by the browser.)

So the tool providers are in a tough position because some of their main outputs, like HTML Help, are easy to add to the tool but are in decline. The outputs that are growing in popularity, like WebHelp, require a lot more work on the providers’ parts.

On a side note, you can use DITA in any authoring tool that can import XHTML. Simply convert the DITA to XHTML and import the XHTML files into the authoring tool. The drawback is that you lose the DITA-ishness of the original files.

Re the question about Eclipse Help – I’m not that familiar with Eclipse Help yet, but it’s on my list of topics for future blog entries. In the meantime, Sarah summed it up nicely in her comment. There’s a lot of information about Eclipse Help available on Google.

Re Sarah’s comment – See above, and thanks for the feedback. As far as BBQ is concerned,
see my BBQ page and look up the BBQ Rib Ranch in Sanford, FL, where I ate at the end of April. A gem…

Re Michael’s comment – Excellent points, thanks. The one thing I’ll add, which you sort of said at the end (“no one promised us that everything would be easy”), is that the level of complexity in the approaches you describe will limit these approaches to a very small and advanced subset of help authors.

Wednesday, May 2, 2007

HTML Help vs. WebHelp

A classic question when creating online help or documentation is what output format to use, HTML Help or WebHelp? It’s important to pick the most appropriate format for your project. Fortunately, modern authoring tools are flexible enough that you can change the format during a project if you picked the wrong format when you began.

HTML Help

HTML Help is a format from Microsoft, and the successor to the older Windows Help, or “WinHelp,” of the late ‘80s and early ‘90s. Microsoft created HTML Help around ‘95 and introduced in February, ‘97. This means that HTML Help effectively predates the web, and it shows.

HTML Help is “compiled” – all the files that make up a finished help project – the topics, graphics, and control files – are contained in one file with a CHM extension that gets distributed to the users. So if you have one topic, you get one CHM file. If you have one thousand topics, you get one CHM file…

HTML Help’s Technical Requirements

HTML Help has three requirements:

Platform - It only runs under Windows. It won’t run on a Mac, Linux, Unix, etc.

Browser - It only runs under Internet Explorer (IE). IE need not be the default browser, but it must be on the user’s PC.

Location - It can only run “locally,” on a drive on the user’s PC. It was not designed to run on a web server but, until recently, could run on a network drive. However, security patches to Windows and IE now largely prevent this.

Pros and Cons of HTML Help

On the pro side:

Standard interface - Although developers can customize the interface, the basic interface is always the same – a toolbar at the top of the screen, three navigation tabs (Contents, Index, and Search) at the lower left, and the main topic at the lower right. So once users learn how to use one CHM, they know how to use them all.

Distribution - Simple. Just send the CHM.

Security - The CHM is compiled, and thus “closed,” so users can’t alter the text.

On the con side:

Outdated - The CHM looks proprietary and dated compared to the webbish look that today’s users are accustomed to.

The future - HTML Help’s use of HTML puts its technical future in question as XML begins to dominate. Microsoft could fix this by upgrading HTML Help, but Microsoft has been trying to move past HTML Help for years. Microsoft tried to replace it in the early ‘00s with a format called Help 2.0, but Help 2.0 never took off. Vista, the new version of Windows, has its own XML-based help format and, as Vista begins penetrating the market, Microsoft seems likely to shift resources away from HTML Help.

Confusion - The name “HTML Help” can be confusing. Listeners may think you said “HTML help”, which is not the same as “HTML Help.” The latter is a formal format, but the former is simply any web site that offers help and is written in HTML. I saw one project that got derailed for ten months because of this confusion. Be certain that your listeners understand that you mean “HTML capital-H Help.”

WebHelp

WebHelp was originally created by eHelp, the original maker of RoboHelp, in early ‘98 in response to the limitations of HTML Help. Today, every help authoring tool has some version of WebHelp.

WebHelp is “uncompiled HTML” – all the files that make up a help project – the topics, graphics, and control files – remain as individual files within an output folder that gets distributed to the users. So unlike HTML Help, where you always have one distributable file, you’ll wind up with dozens, hundreds, or even thousands of files with WebHelp. In effect, WebHelp is just a web site oriented toward online help and documentation.

WebHelp’s Technical Requirements

WebHelp’s requirements are basically the opposite of HTML Help:

Platform - It runs on almost any modern platform – Windows, Mac, Linux, UNIX, etc.

Browser - It runs on almost any modern mainstream browser – IE, Firefox, etc.

Location - It can run locally, on a drive on the user’s PC, but also from a web server or network drive.

Pros and Cons of WebHelp

On the pro side:

Webbishness - WebHelp looks like, and in fact is, a web site. So users will find it easier to learn because it will look familiar.

Vendor-independent - WebHelp is not tied to one vendor, the way HTML Help is to Microsoft. There’s less risk of your help format suddenly becoming unsupported.

Flexibility - The almost unlimited platform support, browser support, and file location offers almost unlimited distribution flexibility.

On the con side:

Distribution - Simple because there’s only one folder to distribute, but that folder may contain hundreds or thousands of files, which will make your network people unhappy. However, the fact that each topic is a separate file means that users are downloading smaller files than they are with HTML Help, thus reducing the load on your network.

Security - Because WebHelp is uncompiled, and thus “open,” users could alter the text in a topic file. This may be a serious risk.

So which Format Should You Use?

You’ll want to take your own specific requirements into account but, in a nutshell, use:

WebHelp if you need the distribution flexibility and the webbish look.

HTML Help if you need a pre-Vista Microsoft-standard look or want to “lock” the help to prevent users from modifying the content.