Questions from the July 7-10 Remote Flare 5.2 Course

Re looking for the definition of "inline marker" as an impromptu test of the help's usability... I found it in under a minute by opening the help Search pane, searching for "inline", clicking "inline markers" in the auto-complete panel, opening the first topic - "Frame Contents Window Pane," and scrolling down until I found the two words highlighted. Here's the definition, from the v. 5.2 help...

"...markers for all inline elements in the active topic. You might find this feature useful if you have imported DITA file content. The reason for this is that DITA inline tags are often for semantic purposes, rather than for changing the look of content. By enabling the inline markers feature, it is easy to tell when particular content is using a tag."

The problem here is the need to scroll almost halfway down the topic to find the definition. However, the highlighting helps. So I'd call this pretty usable...

Can You Use a Help Authoring Tool As A Content Management System?

An upcoming vendor-neutral webinar presented through MadCap Software...

If your documentation group is considering adopting a CMS, you may find that training, workflow, and cultural hurdles can make implementation harder than you think. And even a simple commercial CMS is far more expensive than traditional authoring tools, so those hurdles can get expensive.

Help authoring tools (HATs) like Flare and RoboHelp seem unrelated to CMSs, but HATs have gone far beyond their help authoring roots. They offer, or are starting to offer, features like repositories, version control, review management, content customization using conditionality and variables, and more. HATs today are effectively lightweight CMSs.

This means that if you're planning to move to a CMS, you may be able to use your current HAT to create a simulated CMS to find operational problems before buying the "real" CMS. You may even find that you can use your HAT as your CMS, saving a lot of money and upheaval. That's the subject of this webinar.

This webinar will take place on Thursday, March 12, from 9 AM to 10 AM PT. For information or to register, go to www1.gotomeeting.com/register/187845873. For information about other MadCap webinars, go to www.madcapsoftware.com/training/webinars.aspx

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 www.adobe.com/ and search for AIR. To download the RoboHelp Packager for AIR, go to www.adobe.com/products/robohelp/robohelp-packager-for-air/

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.

Chrome - the Google vs. Microsoft War Heats Up...

After a three-month hiatus, the blog is back...

In February, I wrote a column called "The $44.6 Billion Paradigm Shift" for STC's Intercom magazine. The column looked at Microsoft's aborted attempt to buy Yahoo and what that meant strategically. The gist of the column was that Microsoft saw a long-term threat from Google as the latter works to shift applications from the desktop to the web. Such a shift would make Microsoft's domination of the desktop irrelevant and cause a disastrous cut in Microsoft's revenue stream. (If you don't need the desktop, you don't need Windows...)

The latest sally in this war comes from Google with its release of Chrome in early September. On the surface, Chrome is just a browser. But it also offer an environment in which to run applications like Google Docs, without going through Windows. It has a ways to go today; we're looking at v.1 or, more accurately, a beta v.1 that really uses the Chrome interface to launch the application, which then opens in your regular browser. But the idea is likely to be refined in later releases, just as Microsoft went through several early releases of Windows before getting it (largely) right. If you remember the infamous Microsoft Bob, you get the idea.

I'll discuss Chrome in more detail in my Bleeding Edge column for STC's Intercom. If you're not an STC member but would like a copy of the column, email me at the beginning of November.

One side note about Chrome - how does it work with the output from popular help authoring tools. In a totally unscientific test, I tried viewing two different WebHelp projects through Chrome, one created in RoboHelp 7, the other in Flare 3.1 and then imported into Flare 4. The results?

Everything seemed to work in the Flare project - graphics, links, formatting, and navigation tabs (TOC, Index, etc.)

Almost everything seemed to work in the RoboHelp project. The graphics, links, and formatting all worked, which makes sense since they're basically standard HTML. But I ran into two problems. First, when I opened a topic containing a Captivate movie, the movie display box appeared but a message indicated that I needed to download the Flash player. I did and the movie ran fine, but I'm not sure why I had to download the player since it was already on the machine. More serious was the fact that the navigation tabs displayed but the TOC and Index tabs were empty. More research on the horizon...

Remaining Questions From Remote Flare Course

Sorry about the delay, folks. Here are the answers to the remaining questions…

How to control the indent of a table – To set a global indent, open the Stylesheet Editor, select the tr style, open the Box properties group, and set the indent by using the margin-left property. To set an indent for one table, or one group of tables, create a new style class under the tr style, such as “table indent style 1” or the like, then select the new style, open the Box properties group, and set the indent by using the margin-left property.

Find Results window not displaying – If you recall, the Find Results window didn’t open when I ran a search in the advanced course. This was due to some undetermined layout setting. To fix this, reset your layout to the default (Window > Layouts > Reset Window Layout…) and try the search again. The Find Results window should display perfectly at the bottom of the screen.

Is there a “Keep With Next” or “Keep With Previous” setting for print out- put to prevent two page elements from splitting across a page break, such as keeping a paragraph and a numbered list together? – Yes, but it’s not labelled as such. In the Stylesheet editor, open the PrintSupport properties group for the style that you’re formatting and select either the always or avoid value, as needed, for either the page-break-before or page-break-after property, as needed.

First Issue From the 7/21-7/22 Advanced Flare Course

Re the exercise on page 103 about finding and removing unused style classes from a CSS - I looked in the original dept_styles.css file, in the Files folder, and it does contain the p.temporary class. This means that I probably accidentally deleted p.temporary from the css in the project when I was moving other style classes out from under the Print Medium. So you should have found p.temporary in the dept_styles.css file that you imported into the project and should have been able to delete it per the exercise.

More to come over the next few days.