Review of Adobe RoboHelp 8
Click a link below to jump to a particular section; click any "
When you first open the recently released version 8 of Adobe RoboHelp, you might get the initial impression that little has changed since version 7. In fact, this is very far from the truth: although the main user interface (which was heavily reorganized in version 7) is much the same as before, scratch beneath the surface and you'll find a number of highly significant changes and additions. These include innovative and effective solutions to some of the long-standing flaws in RoboHelp, such as its handling of lists in HTML, and its ability to work with source content stored in Word or FrameMaker. There's also complete built-in support for the new Adobe AIR Help format, which enables users to share comments and feedback on the Help.
RoboHelp's own Help system, which was heavily criticized in version 7.0 has been updated and improved, though still lacks some of the clarity and rigor of the Help for RoboHelp X5 and earlier versions. In common with other current Adobe products, it is now displayed within the Adobe Help Viewer 2, which is based on Adobe AIR technology. This means that it is possible to search for and view a combination of content both from the Help system and from the web-based Community within a single interface. It also enables users who have registered an Adobe ID to provide feedback on the Help.
Figure 1: RoboHelp's Help in Adobe Help Viewer 2
However, the layout of the Help is rather different to the tri-pane format that RoboHelp users have become accustomed to. The Adobe Help Viewer uses a single pane to display either the table of contents (TOC) and topic content side-by-side, or the search results. This means that the TOC disappears out of view as you scroll down long topics, and the search results list cannot be viewed alongside topic content. It is not possible to replicate this layout from RoboHelp itself, which prevents authors from being able to use RoboHelp's own Help as a model for their own development.
One more comment about the Help (and I make no apology for focusing on RoboHelp's user assistance given the nature of the tool): I notice that it no longer contains any window or dialog box topics. These screen-based reference topics have in the past been used as the targets for context-sensitive links from RoboHelp's various windows and dialog boxes. They have now been replaced by procedural topics. For example: clicking Help on the redesigned Styles dialog box displays a set of step-by-step procedures (not all of which are specific to the Styles dialog box) under the general heading "Create styles for style sheets". This migration towards procedural context-sensitive Help is a growing trend within the software user assistance community, and one that I plan to discuss in depth during my presentation on context-sensitive Help design at the 2009 WritersUA Conference. Personally, I find it more difficult to find answers to my specific field-based questions in these kinds of topics, and I mourn the passing of the screen-based reference topics!
One of the most welcome improvements in RoboHelp 8 is the continued movement towards cleaner and simpler source code. Following the eradication of Kadov tags in RoboHelp 7, version 8 has further cleaned up its act by adhering to strict XHTML. This means, for example, that all attributes have quotation marks, and all unary tags such as <img /> and <br /> are closed. The coding of lists has been much simplified by the introduction of two new types of style: a list style that enables you to apply classes to the li element, and a multi-level list style that enables you to create complex nested lists with different types of formatting and numbering at each level. As a result of the list style, a list can now be coded without the use of a p element as follows:
Although it may not seem terribly impressive, this greatly simplifies the formatting and management of lists within RoboHelp, which has been a source of confusion in the past.
A critically important aspect of RoboHelp is its support for Cascading Style Sheets (CSS), the technology used for all topic formatting. In RoboHelp 8, the user interface for editing style sheets has been completely revamped with a radical overhaul of the Style dialog (effectively RoboHelp's CSS editor) and the introduction of a Styles and Formatting pod (see Figure 2). This new pod makes it quicker and easier to add new styles and to edit existing styles, and it is displayed by clicking Format > Styles (which used to display the Styles dialog in previous versions of RoboHelp).
Figure 2: Styles and Formatting pod
The Styles and Formatting pod takes a bit of getting used to when you are accustomed to the old Styles dialog, particularly as it has no obvious controls and relies on right-clicking the required style to display a context menu of options. However, after using it for a while I have now found that it gives me access to almost everything I could possibly want to do, and I regard it an improved and more streamlined way of working with styles.
I think Adobe have done a great job in this area, and I have only a couple of small gripes: the first is that the UI does not encourage you to use the all-powerful "Background + Text (BODY)" style, which is not listed within the Styles and Formatting pod. To edit this special style, I have to open the full Styles dialog (by double-clicking the style sheet in the Project Manager pod) and look for it in the "Other" styles group.
My second minor gripe is that the UI does not encourage you to exploit inheritance I would like to be able to easily clear a formatting property (such as font-family) to allow it to inherit from its parent element (usually either body or p). To do this, I have to open the Styles dialog and delete the property value there. By the way, if you're not already taking advantage of inheritance and the "Background + Text (BODY)" style, you should consider doing so this strategy enables you to specify a default font-family and size in a single location within your style sheet, making your CSS leaner and easier to maintain. For more information on this, see the W3C documentation or Adobe Developer Connection.
In addition to the new list style types, RoboHelp 8 also introduces table styles for the first time. Based on the principal of descendant selectors, these represent an extremely powerful and well-conceived way of applying a complex set of table formatting characteristics (including special formatting, if required, for first row, first column, even and odd rows, etc.) to an entire table at a single stroke. RoboHelp provides a set of predefined table formats (variously and somewhat confusingly referred to as "Table Templates" and "Global Table Styles" within the UI and the Help) to which you can add your own. The process for doing this is rather glossed over in the Help, and is a little more involved than you might have been led to expect. These Global Table Styles are available to all projects. However, once applied to a table within a project, the table style is then copied into the project's own style sheet this means that any changes you make to the style are not reflected in the Global Table Style, and there is no easy way of ensuring that the tables within multiple projects remain consistent.
Figure 3: Select Table Style Dialog showing available Table Templates (Global Table Styles)
Following on from the previous paragraph, a similar point regarding global control and consistency could be made in relation to the new Resources pod. This provides access to a central repository of items such as style sheets, images, and snippets that can be easily copied from the Resources pod into any project. This is quite a convenient little tool, but the limitation again is that the files are simply copied into the projects, and they retain no link back to the central repository. It is therefore not possible to effect global changes across multiple projects by editing the files in the Resources pod. I look for this as a very useful and exciting possible enhancement in future versions of RoboHelp.
RoboHelp 8 now enables you to link Word or FrameMaker documents to your RoboHelp project; you can convert items such as the table of contents and cross-references to the equivalent items in RoboHelp, and map individual styles to the RoboHelp styles within your project. Where this is different from importing documents (which you've been able to do for many years with RoboHelp), is that you can continue to maintain the linked documents outside of RoboHelp, and the corresponding content will be automatically updated in RoboHelp. This effectively enables you to use RoboHelp as a "publishing engine" for transforming Word or FrameMaker content into a range of Help formats. It has only previously been possible to do this with FrameMaker documents, and then only if you had the special enhanced versions of RoboHelp 7 and FrameMaker 8 within the Technical Communication Suite 1.
The UI that supports this new workflow is unfortunately far from intuitive. There is a lack of natural flow or sequence to the operation of linking and setting up conversion settings, and it is difficult to find useful guidance either within the UI or the Help. Once you learn that the conversion settings are to be found within Project Settings then things get easier, but even then the dialog boxes and controls are somewhat opaque. It's easy, for example, to overlook the Pagination option, which is essential for splitting a long document into separate topics at the headings (see Figure 4). The entire linking workflow would have been a ideal opportunity for inserting embedded user assistance within RoboHelp's own user interface, and I hope for improvements to the UI in the next version.
Figure 4: Word Conversion Settings showing Pagination option
Probably the most important and noticeable enhancement from the point of view of the end-user of Help generated from RoboHelp is the greatly improved search functionality in WebHelp, FlashHelp, and Adobe AIR Help. These formats all now rank the search results in order of best match, and provide the options of substring search (enabling users to enter only part of a word in order for it to result in a hit) and of showing context in search results (which causes the first few words of the topic to be displayed in addition to the title). Finally, and hugely significantly, search now also targets the keywords that you have assigned to each topic through the index. This means that, even though you might not choose to display an index pane (how many users these days opt for an index in preference to search?), you may still find it very worthwhile compiling a comprehensive index including synonyms and related terms as a way of enhancing the user's search experience. Of all the new features in RoboHelp 8, this is probably the one that I would least want to be without.
"Master page" is a new term in RoboHelp 8 however, it is simply the name for an improved version of the topic template that has been available in RoboHelp since version 2002. Master pages contain the same three sections (header, body, and footer) as before, but introduce the concept of a "body placeholder" that displays the body content of the topic to which the master page has been applied. This allows the extra flexibility of inserting content within the body section but above the body placeholder. While initially I couldn't see the point of this, it turns out to provide a way of exploiting the newly introduced breadcrumbs placeholders. As shown in Figure 5, if you insert a breadcrumbs placeholder directly above the body placeholder (for some reason, placeholders can't be inserted into the header section), it causes a breadcrumbs link to be displayed within every topic to which the master page has been applied. This new system of master pages and breadcrumb placeholders means that it is now possible to insert breadcrumbs into any Help output format, including Microsoft HTML Help.
Figure 5: Breadcrumbs placeholder inserted above body placeholder
While on the subject of placeholders, there is a new mini TOC placeholder that resolves to a set of hyperlinks to all the headings within the current topic. This is not quite the same as the mini TOCs found in other tools such as MadCap Flare and WebWorks ePublisher, which typically provide links from "parent" topics to "child" topics based on the hierarchy of the main TOC there is still no way of doing this within RoboHelp. However, the RoboHelp mini-TOC placeholder does provide a convenient way of easily inserting a self-maintaining set of shortcut hyperlinks at the top of long topics. This is a technique that Adobe now uses a lot in its own Help systems.
A very useful new feature of master pages is that it is now possible to specify an "override" master page to be automatically applied to all topics at generation time. The setting for this is in the single source layout options (see Figure 6), which means that it is potentially possible to apply a different master page in each single source layout (or output). So, for example, you could add a WebHelp single source layout for a specific customer that used a master page to display that customer's logo in the header section of each topic. Another advantage of this feature is the ability to apply master pages at generation time even to topics that are sourced from a linked Word document or FrameMaker book.
Figure 6: Master page override in WebHelp single source layout settings
When you install RoboHelp 8, you are offered the option of installing the Adobe ExtendScript Toolkit CS4. This adds a new Script Explorer pod to the RoboHelp environment, which gives you the ability to create and run scripts that automate complex or repetitive tasks within the RoboHelp UI. A number of sample scripts that you can use or customize are provided by Adobe; for example, there are scripts for counting the number of words in a RoboHelp project and for saving the current project as a project template.
Figure 7: ExtendScript Toolkit
The Glossary Hotspot Wizard has been given a long overdue update. Even though its UI looks exactly the same as before, there is an important difference in what it actually does under the hood: instead of inserting the text for the glossary definition into each topic containing a term, it now simply places a special marker around the term within the topic text. The current definition is then inserted at generation time. This means that it is no longer necessary to re-run the Glossary Hotspot Wizard whenever you change a definition in the glossary.
User-defined variables, which previously could contain only plain text, may now contain images and hyperlinks. They may also have font formatting associated with them; strangely, however, it is not possible to use character styles within the variable editor, so the formatting must be applied as inline font settings (not something I normally recommend).
Twisties are now supported for expanding hotspots, drop-down hotspots, and glossary terms. If you don't know what twisties are, the term apparently originated from Lotus Notes and is used for the little icons (usually a triangle like this ) that are displayed beside DHTML hotspots. When you click on the hotspots to reveal the hidden context, the icon is substituted and appears to twist (like this ). In previous versions of RoboHelp it was possible to implement this behavior by inserting a custom script it is now simply a matter of selecting two images (the "closed" and "open" versions) within the Styles dialog for the appropriate character style (see Figure 8). Although the feature is useful and most welcome, I am surprised at its lack of supporting resources. Adobe does not provide sample twisties settings within the default style sheet, and I could find no suitable twisties icons within the RoboHelp Gallery of images.
Figure 8: Selecting twisties images
There has been a enhancement to the behavior of merged WebHelp and FlashHelp projects it is now possible to select a setting within "child" projects that causes the full merged TOC to be displayed when the Help is opened, instead of simply the child project's own TOC. Unfortunately for authors who generate merged HTML Help systems, the same functionality has not been added for this format.
A golden rule in previous versions of RoboHelp was that the Project Manager always listed topics and folders in strict alphabetical order. This is no longer necessarily the case: you now have the option of arranging the topics in your own custom sequence or of having them listed alphabetically as before. I can imagine that Adobe might have received a lot of requests for this feature, although personally I can't see myself ever wanting to move away from an alphabetical listing. An advantage of the custom sequence is that you can arrange the topics and folders as you would like them to appear in the TOC, and then use the Auto-create TOC command to regenerate an up-to-date version of the TOC at any time during development or maintenance of your project.
RoboHelp 8's enhanced language support means that you can now specify a language at the project, topic, and paragraph level. This could be helpful, for example with spell checking, in projects containing text in multiple languages.
Overall RoboHelp 8 is a very impressive new release. Whereas version 7 was most notable for a complete overhaul of the user interface, most of the changes in RoboHelp 8 are beneath the surface. They are no less significant for that, however. RoboHelp 8 offers the possibility of new workflows for single-sourcing high quality print documentation and online Help by linking Word and FrameMaker documents to RoboHelp projects. It also adds a wide range of powerful productivity enhancements for the author and improvements to the experience of the end user of the generated Help. In my view, it seems a pity that Adobe chose not to showcase features such as the glossary and DHTML drop-downs with twisties in its own Help for RoboHelp, although I understand its need to be consistent with the Help for other Adobe products. Top of my list of favorite features in RoboHelp 8 is the enhanced search in WebHelp/FlashHelp, and especially the fact that index keywords are now included within topic metadata as targets for full-text search.
For further information on the full range of features in Adobe RoboHelp 8, see the Adobe RoboHelp 8 product page.
Matthew Ellison has more than 20 years of experience as a user assistance professional in the software industry. He has been a popular speaker at WritersUA events throughout the world since 1997, and is now Director of the UA Europe Conference. Matthew holds a B.Sc. in Electronic Engineering and a Post-Graduate Certificate of Education from Bristol University in the UK. He is an Adobe Community Expert for RoboHelp.