Saturday, November 8, 2008

AIR and Tech Comm

For those people who got tripped up by the webinar ID change on Thursday, November 6, here’s the AIR overview that we covered.

AIR (Adobe Integrated Runtime) is a fairly new output type from Adobe that’s a hybrid of a browser-based application and a desktop application. Adobe is implementing AIR across its product lines, and AIR is showing up outside Adobe as well, in the new release of MadCap Flare for example. Here, I’ll discuss AIR from one perspective – online help and documentation created using RoboHelp (and other tools like Flare).

First, a little history to put AIR in context…

In the late 1980s, Microsoft released Windows Help (“WinHelp”), the first mainstream online help format. One of WinHelp’s attributes was that it was “compiled”, combining all the topics in your online help or documentation into one file, the HLP, for distribution. (There was one more file, the CNT, but we can ignore that here.) Whether you had 1 topic or 1,000 in your help, they were distributed as one HLP file. This one-file model made WinHelp easy to distribute.

In 1997, Microsoft released WinHelp’s successor, HTML Help. It too was compiled into and distributed as one file (no CNT this time), the CHM. As with WinHelp, the one-file model made HTML Help easy to distribute. But this time, the model got tripped up by the spread of networks in general and the web in particular.

HTML Help wasn’t designed for a web-based world or non-Microsoft world. This meant it could only run on Windows PCs with IE, and could only run locally or from a network drive. As people began turning toward the web, and as other formats like Linux began to take off, HTML Help began hitting its limits. This happened pretty quickly; as early as mid-1997 people were complaining about how Microsoft-centric HTML Help was.

In late 1997 or early 1998, eHelp came out with a solution – WebHelp. WebHelp looked similar to HTML Help but didn’t bundle the topics into one distributable file. Instead, WebHelp kept topics as individual files that were managed by various control files. In effect, WebHelp was a web site with a documentation-like interface. This added great flexibility. WebHelp could run on almost any platform and browser and from any location (local, network drive, or server).

But it had some problems. Because it was not compiled, a WebHelp output had as many files as there were topics, graphics, and control files. A 1000-topic WebHelp system might have 1500 files, which made engineering and network management very unhappy. (“Fifteen-hundred files! For a help system!?”) Plus WebHelp places a heavy testing load on vendors since it has to be tested under and reconciled for different browsers and new versions of existing browsers.

So the ideal solution would be an output format that could run locally in order to reduce network traffic, that went back to the one-file model of WinHelp and HTML Help, that got away from the browser compatibility problem, and that was network aware… AIR.

When you convert an online help or documentation project to AIR, the AIR “packager” bundles the topics, graphics, and control files into one file with an AIR extension that runs locally. It avoids the browser compatibility problem by using its own viewer. It’s network-aware to handle updates. It has WebHelp-style attributes like the ability to use skins to customize the interface. It lets you create links to external targets like web pages and can run them in separate windows. Plus, because it’s running locally, it can take advantage of local features like file writes. For example…

The screen below shows a simple WebHelp project created in RoboHelp HTML 7. It has the usual tri-pane features, some formatting, and a link (“Show me how”) to a SWF movie created using Captivate.

The next screen shows the same WebHelp converted to AIR. It keeps the tri-pane look and the link. The formatting got lost on conversion but can be recreated. This output also adds the “Resources” link at the top right which offers a drop-down list of external links. Note also that there are two pages open – Base Conversion and Hyper/Word Services – each in its own tab.

So the output would call for some minor tweaking (which should decline in later releases of AIR), but all in all, a good thing…

On the minus side, several things to consider:

AIR requires that developers (not viewers) have the JRE (Java RunTime Environment) on their PCs. This isn’t a big deal, but Sun’s download page can be a bit confusing.

AIR’s use of a proprietary viewer instead of a browser isn’t a big deal unless you support “zero-footprint” environments where viewers can’t download anything to their PCs. That means they won’t be able to download the viewer and thus can’t view the AIR file. This is a problem now but history suggests that it may lessen. For example, in 1997, WebHelp developers couldn’t be sure that viewers had any browser; today, it’s taken for granted. In 1999, developers couldn’t be sure that viewers would have the Flash Player; today, according to Adobe, 99% of all web-capable PCs have it. The AIR viewer is the latest in the “we’re not sure if users have it…” category but, if AIR takes off, the viewer may turn into one more default feature on users’ PCs.

AIR’s ability to use local PC features can be a security risk. Adobe is attempting to deal with this by requiring that developers create digital certificates for their AIR applications.

To sum up, I don’t know what the AIR’s future is but Adobe is making a big push for it and it’s definitely worth a look. For more information, go to and search for AIR. To download the RoboHelp Packager for AIR, go to

Friday, November 7, 2008

Answer to Mimic Question from DocTrain East Workshop on Nov. 1

Let's say that you create a text caption box in a Mimic movie frame, add some text that includes a variable, and size the text caption box so that its borders fit tightly around the text. Furthermore, let's say that the value of the variable is "ABC".

If you then change the value of the variable to a longer entry, such as "MadCap Software, Inc.", might some text be pushed outside the borders of the text caption box? Yes.

If so, how do I fix this to be sure that all the text fits inside the borders of the box? You have to adjust the size of each text caption box by hand. A better solution is to size each text caption box whose text contains that variable so that all the text will appear inside the box when the variable's value is set to the longest possible entry - e.g. "MadCap Software, Inc." This way, you know that all the text will appear in the box when you use shorter variable values. There will be some excess white space in the box, but you won't run the risk of having to modify the size of the box every time you change the value of the variable.