Feature: Adobe/Macromedia's Robohelp Word is the 2nd half of this documentation tool
Motivation: A second look at creating help files with Robohelp

RoboHelp ($999US)can be divided into 2 parts - RoboHelp HTML and RoboHelp Word. RoboHelp HTML uses a HTML as its basic save file format - generating code for FlashHelp, WebHelp, JavaHelp and their variants but not WinHelp 2000, WinHelp32 and WinHelp16. RoboHelp Word uses Microsoft Word and the RTF file format to store basic help file data and it can generate most of the WinHelp formats with the major exception of Winhelp Pro (server based HTML help). Finally RoboHelp Pro ($1899US, there is also a .NET version of the Server tool for $1999) includes the two RoboHelp desktop versions but adds a whole slew of server based features to the RoboHelp product line:
Server Output and Services
 - natural language-like search
 - automated fallback to local help
 - realtime updates to helpfiles on server
 - feedback reports on specific topic usage patterns
Version Control and Content Management
 - Multi-author support with helpfile checkin and checkout
 - password security to support file-access rights
 - version control and archiving services with rollback
 - time+date stamping along with version comments
 - helpfile comparisons, histories and audit trails
 - compatible with popular version control systems
Distributed Workforce Support
 - telecommuters on dialup have fast checkin and check out services
 - workers can go offline and later resynchronize their work
 - server allows multiple offices/locations access to helpfile development
 - ditto for administration services
So Robohelp is geared for large project use as well as single technical writer or documentation specialists. With these features in mind and having seen RoboHelp HTML at work creating some simple web-based help files, lets explore the RoboHelp Word side of the tool seeing how adept it is at creating Windows help files.

RoboHelp Word

We are going to use RoboHelp Word to create a helpfile which explains How to Replace IE-Internet Explorer with Firefox. The helpfile will use many images and local plus external hyperlinks and also try to show off some of the features of RoboHelp Word.


As one can be seen from the screenshot above just after launching RoboHelp Word, Word and RoboHelp are closely integrated together. Specifically there are numerous new or Robo-enhanced commands added to both the menus (Insert especially but also the new RoboPDF and Robohelp menu items) and the icon toolbars (the bottom two rows of icons on the Word screen are all RoboHelp commands). In addition, RoboHelp has eliminated and/or grayed out the many Word commands such as drop shadow, 3d-styling, stroke coloring, block bordering, etc that do not carry through to helpfiles. Except for the need to resize the two programs separately, this reviewer was amazed at how closely the two programs worked with each other.

The layout is quite simple - for each help topic there is a page in the master source file in Word, helpfile.doc. There is a minimum of special control characters exposed to users in helpfile.doc - but as you can see associated with each topic header there are some special control characters that should not be changed or deleted. Other than that proviso users can employ Word or the RoboHelp Explorer interchangeably to great effect. RoboHelp supports Word 2003, 2002, 2000 and 97.

The Replace IE Helpfile
The Robohelp Explorer windows looks almost identically the same as its RoboHelp HTML counterpart - with treeview layout nearly the same and the Topics, TOC, keywords, Index and Tools tabs at the bottom identical in layout and function.

For this helpfile, it was decided to enter the six topics in skeleton form right from the start:
 - Welcome - this topic gives a quick overview of the advantages of Firefox over IE;
 - Detailed Firefox Installation Instruction - is the key downloading and getting started topic;
 - Initial Setup of Firefox - walks through PC Setup;
 - Additional Info - has reference links for Firefox;
 - Wall Street Journal Review - a popup testimonial;
 - Washington Post Review - another popup testimonial.

Only the Topic header and the connecting links/jumps between topics were added. To add a topic is the familiar CTRL+T shortcut or in Word Insert | New Topic . Immediately, the new topic appears as a new page in Word with the title of the topic as header (users can easily change this header in Word including all of the default formatting and styling as required.

For example, the header was increased in fontsize and bolding in all our topics. the next thing we added to all the topics was a navigation bar just beneath the header. A jump in RoboHelp Word is also simple to add to a topic. Just use the Insert | Jump menu command (or CTRL+J) to add links between topics.
As you can see from the screenshot at the left, setting up the jump is simple. Just type in the Hotspot Text - "Additional Info" in this case and then point and highlight the name of the associated Topic in the list in the middle of the dialog - Additional_Info in this case. Click OK and the link is done.

We proceeded to setup a Previous Topic, Next Topic set of links just below the header just like in the RoboHelp HTML sample - and for the same reason. Although RoboHelp does provide automatic navigation aids - its is worth your while to set your own because the alphabetical order or skipped subtopics of RoboHelp's auto-navigation tools sometimes just do not work the way you want.

The next feature we took advantage of was the Insert | Help Popup... (or CTRL+P) which creates a popup help dialog. The dialog contains extra help material that you don't want cluttering up a topic. But if the user is interested, by clicking on the topic link, it pops up and over the currently viewed topic. As soon as the user clicks on the popup topic it disappears. This feature is available in RoboHelp HTML but we did not take utilize it. Finally, the popup topic itself is available in Word and can be edited with all sorts of "surprise features" as required. the on restriction - those features should not rely on a mouse click because that immediately collapses the popup.

The next feature we used, a navigation button is hard to duplicate in RoboHelp HTML but easy to use in RoboHelp Word. Just place the cursor where you want a button to appear (on the bottom of the page in our case); and then choose Insert | Help Button... and the dialog shown at the left pops up. Again, RoboHelp Word makes it very simple to create although users have to be a little careful with this dialog. Enter on Button Label: the caption you want for your button. For the Button type pulldown stick with the default setting, Authorable. You can try the other options which include using your own graphics buttons with up and down state images if you are into maximum customization.

Again from the list of topics, point to the topic that you want to jump to. Now the Action Type pulldown contains the real power of this Help Button feature. You can choose the default, which meets our needs which is Jump. When clicked this will cause the user to jump to the next topic in sequence. However, users are not limited to the Jump Action type. There are 6 other choices:
External Topic - this is your way of linking two or more helpfiles interactively
HTML Jump - this is the only reliable way to jump to an external Web link
Macro - allows for any of the special RoboHelp macro commands
New Popup - creates a new popup topic
Popup - points to an existing topic and has it popup
See Also - points to a list of See Also Topics

Developers will find themselves spending a lot of time around the Insert Button command in the process of adding advanced features to their help files. Some of these commands require settings in the generation phase (see Extensions below). Also some commands do not carry over to RoboHelp HTML - see documentation for all the details.

Finally be forewarned - the Hyperlink command in Word does nothing when the final helpfile is generated. Users must use the Insert Button command to enable mailto: and external Web hyperlinks. Do not be fooled by the seeming active blue links - they do not work when translated to helpfile format.

So with this Insert Button we add the final external references to the Additional Info topic and we are done filling in the topics. Now we are ready to generate the Helpfile.

Generating the HelpFile

Just as in RoboHelp Help, the setting of File | Project Settings command is critical. When project Settings dialog pops up choose the Project tab and check the Primary Output/Layout pulldown. Set it to WinHelp 2000 or Winhelp 3 or WinHelp 4 to get the formats exclusive to RoboHelp Word. We chose Winhelp 2000 and the resulting helpfile is what is available for download here.

But lets follow the steps in generating the WinHelp200o helpfile to see the options users have available for customizing their final helpfiles. First users determine the output folder and helpfile name - and we take advantage of that option storing the helpfile in a newly created Winhelp2000 directory.

Multiple files could be used for in creating a helpfile - ours uses only one. As default topic we choose the Welcome topic. And there are no conditional build expressions; but this allows for the same helpfiles to be used for generation to different platforms with varying topic, content and helpfile functionality. Click Next to jump to the second dialog.

Here we attach the Copyright and citation notices and set the output target. In this case its a shipping run with maximum compression on. Extensions is an important button to click if you are using any external HTML file references like we are. Click the button and then select the first two options - otherwise the right .DLLs will not e used in processing.

The Batch Files buttons allow users to setup pre and post compile processing which is quite important in large helpfile generation for multiple platforms or special conditional processing. Again, this is a simple helpfile, so this option is not used. Click Next to go on to the third dialog.

The third dialog is a mix of the mundane with the complex. Add the Title and default helpfile, the RoboHelp defaults generally apply. Users can have a splash window and that would be specified in the Default Window setting. We have checked the Include the helpFile Name with pages option; but there is a cost for this - a CAB file with all the documentation pages is created and it is usually equal to or greater than the size of the final generated helpfile. So be careful when choosing this option - especially when big helpfiles are being generated. Finally you can add your own index files in this step - another special customizing options. Click Finish to to ignore the fourth and final generation dialog.

The skipped dialog involves watermarking the pages and what to display when a topic cannot be found. This is customized helpfile processing for larger installations. The screenshot at the left is the RoboHelp generation and compile process in process. In all our work over the past 3 years including some pretty big helpfiles, we have never had a hiccup in the compile process. This is a quite a change from helpfile creating in the mid to late 90's. The six pages took about a minute to compile on a 261MB 800Mhz PC. Use this as a rough rule of thumb for estimating helpfile compile time If you download the helpfile, you will see it has a lot images which may explain the compile time - lots of image compression to do.

This is the final Results screen. Pay attention to the notes and warnings lines. If there are any errors click on the Error Wizard button which will provide very handy notes and warnings all collected in one place. If you just click close - this service is no longer available to you. Instead you will have to reconstruct problems by means of the RoboHelp tools WinHelp BugHunter and WinHelp Inspector among others. Trust me - if you have problems the Wizard is a big help. And Notes and Warnings often contain showstopper errors.

As in the case of RoboHelp HTML, we changed the target layout and generated Replace IE helpfiles for WinHelp 32, Windows HTML Help and FlashHelp with no problems. Again this was nice "proof" (a 6 topic helpfile is not really challenging) of Robohelp's multiple output versatility.

Summary

With this run through, we were impressed with the ability of RoboHelp to interface nearly faultlessly (we had a late problem with CSS stylings and of course the major problem with Hyperlinks) with Word. It was very nice to be able to import not just Word files but PDF and other filetypes with fair good fidelity - advanced formatting such as borders and drop shadows fall by the wayside; but tables, images, and font stylings transfer well. It was also nice to be able to output not only to multiple help file formats; but also to high quality Word and PDF printed formats. Given the decline of printed manuals and documentation, electronic documentation is having to fill the gap. Being able to fill the gap with repurposed electronic docs is very helpful.

But electronic documentation is changing dramatically - its is moving to Flash and video. Check the Xara site or Siebel site for demos of this trend. Fortunately Robohelp with FlashHelp is well adapted for this trend as it can already utilize Flash animations and Captivate movies among the many sources of Flash and video material. Finally RoboHelp is moving to a server development model with a number of robust characteristics including version control and checkin/checkout faculties and distributed usage. Are these enough to justify the premium pricing ? Well the competition coming from the HTML/Java help quarter plus the the new wave of animation and video documentation products will put that question to the test over the next few years.

(c)JBSurveyer 2005