Adventures with the New Technical Communication Suite from Adobe (mostly RoboHelp 7 and Captivate)

by Tom Johnson on Dec 19, 2007
categories: technical-writing

Rob Houser's recent article in Writers UA, "What's New in RoboHelp 7?", is a thorough, insightful article I highly recommend. After reading his review, I thought I'd post a few notes from my experiences with the same. (For more about Rob, see his site.)

This past month I've been heavily using the RoboHelp 7 and Captivate 3 components of the Technical Communication Suite. RoboHelp 7 offers some impressive new features: snippets, breadcrumbs, a pod-based interface that you can drag around, integration with Framemaker and Captivate, and so on. But as is the case with many new releases, there are some bugs and unexpected shortcomings.

Captivate Integration Led to Fuzzy Videos

I really love the integration with Captivate, and the inclusion of Captivate is what sold me on the product. RoboHelp 7 allows you to begin Captivate movies from within RoboHelp. That way you don't have to keep re-importing the files each time you update them. Additionally, you can directly embed screen demos on topics or in drop-down hotspots.

I think that's the strength of the product, and for the most part it works well. But some glitch happened in RoboHelp that resized my Captivate movies and made them look fuzzy. I ended up deleting the RoboHelp-initiated movies and imported them manually instead (File > Import).

Firefox Display Never Finishes Loading

I was disappointed to see that my custom webhelp skin wouldn't work in Firefox. It loaded eternally and kept trying to load until I pressed the Escape key. The Back and Forward buttons don't store any history (until you press Escape). So when you do finally click Back, it takes you out of the help. Click Forward and it takes you back into the help, but with no TOC pane.

Luckily, there is an easy fix for this. It only involves a quick change to some lines of code. Go to Peter Grainge's site and see the section "Help is slow to complete loading or it fails to complete loading."

Bullets and Sub-Lists Display Differently in Firefox

While you're looking at your project in Firefox, you might want to look closely at your bullets and sub-lists (by sub-list, I mean a, b, c ...). If you apply a style to either of these elements, Firefox's display looks goofy. The bullet or sub-list is left-aligned, while the text is spaced too far to the right.

You might also want to be careful about manually editing the css style sheet. I opened up the css style sheet in Dreamweaver and edited the topics while keeping the RoboHelp project open. It was cool to bypass the tedious style editor and quickly modify my styles like this. However, when I published the file, the output in Firefox was skewampus. In addition to the bullets and sub-lists problem, paragraph spacing was absent. Plus the help's buttons didn't work and the TOC collapsed on a Kubuntu OS.

I recommend using RoboHelp's official style editor, and perhaps playing with the _ns.css stylesheet that RoboHelp outputs when you generate help.

Easy to Drag Panes into Oblivion

The new graphic interface with the draggable panes looks more modern, and you can actually drag the panes onto other monitors. But be careful with this. If you have popup windows that open on a second monitor, when you switch back to single monitor mode, RoboHelp might not know you're only using monitor. I had an Import dialog box that kept opening on a second monitor that I didn't have, and the app would freeze until I hit escape to close the invisible dialog box.

When I switched back to dual-monitor mode, I dragged the Import box where it should appear, and that fixed it.

Webhelp Skin Graphics Lacking

I really wish Adobe would have created more appealing webhelp skins. I think they added one new skin ("Beautiful Vista"), but it's not very beautiful. If Adobe hired more graphic designers to create up-to-date looking buttons, the output could be a lot more attractive.

Online Help Quality Plummets

RoboHelp's online help is interesting. There's an online and offline mode. (The online mode didn't work at first, but they eventually fixed it.) In Rob Houser's review, he noted how the help was careless and sloppy. I'd add the word "uninformative." It seems to lack more comprehensive instructions specific to the Suite.  The help points out the obvious in too many places, without providing real insight.

Rob writes,

I hate to make this observation, but RoboHelp's online help seems to be getting worse. I'm not talking about RoboHelp's ability to output a professional and standard looking help viewer. I'm talking about the help content that is supposed to help you learn and use RoboHelp. The examples may not seem dramatic, but taken as a whole I'm afraid that new users may not be able to learn RoboHelp simply by using the online help. They certainly aren't seeing best practices and full RoboHelp capabilities being demonstrated.

For example, I wanted more thorough instructions on how each component interrelates with the others. When you initiate a Captivate movie from within RoboHelp, the source file (with a .cp extension) remains in your computer's My Documents > My Adobe Captivate Projects folder -- which is outside the RoboHelp project folder. To edit the movie, you right-click the .skn file from inside RoboHelp's interface (in the Project folder) and that skin file opens the .cp file on your desktop. Don't rename the .cp file or the .skn file won't recognize it.

Also, don't manually delete anything from the RoboHelp project folder (such as through Windows Explorer) because doing so will corrupt the .cpd file and RoboHelp will have to re-index the contents of that folder. I wanted more information like that in the help.

Framemaker Import Groundbreaking But Irrelevant for Me

Although the integration with Framemaker is revolutionary, I'd still rather output to a Frame file, rather than import it. Rob makes some noteworthy comments about this interaction:

The import is only one way—from FrameMaker to RoboHelp. However, many RoboHelp features are not supported in FrameMaker documents, so single-sourcing from FrameMaker to RoboHelp would seriously restrict the quality of your help system.

Another big issue: there is no capability for generating the printed documentation from RoboHelp in FrameMaker. This means the main form of printed documentation supported by RoboHelp is still Microsoft Word, which has numerous layout and formatting issues that have not been addressed for over seven years.

In his conclusion, he makes an interesting observation comparing Robohelp to Flare in terms of Framemaker interaction:

Flare is developed by a team that is experienced with help authoring, and—perhaps the most confusing distinction—Flare seems to support FrameMaker more thoroughly both for importing and exporting content than does RoboHelp.

Conclusion

RoboHelp continues to ignore some major issues, such as the lack of character-level indexing and the formatting errors when you export to Word. Despite my complaints, I like many others have an affinity for the usability of this tool. It's like an old pair of sneakers that has some new laces and polish. Maybe some new traction too.