Specialist training on
User Assistance
and eLearning
Review of Help & Manual 5
By Matthew Ellison
First published in Winter 2009 issue of ISTC's Communicator journal
As it name implies, Help & Manual is an authoring tool that produces software Help and printed documentation from a single source. Not as well known in the UK as competing products such as RoboHelp, Flare, and Doc-To-Help, it has nevertheless been around since 1997 and has matured into a feature-rich and polished-looking product. This article provides an overview of Help & Manual Professional version 5.3 and reviews a number of key aspects including its usability, support for information re-use, and the quality of its published outputs (both help and manual!).
Contents
- Overview of Help & Manual
- Help & Manual's user interface in detail
- Project structure and file types
- Publishing options
- Basic Help authoring tasks
- Information re-use
- Skins and templates
- Other features
- Summary
Overview of Help & Manual
Help & Manual 5 is an interesting mix of new and old: it is based on cutting edge technology (with topic content and formatting being entirely XML-based) and includes a number of modern features such as snippets and skins. However, it also retains some of the most useful features and paradigms of long-established Windows Help formats such as WinHelp and HTML Help. For example, it provides non-scrolling regions at the top of topics, and enables graphics to be referenced from a common directory external to the project (both features of WinHelp projects that are now unsupported by most other authoring tools).
The quality of the Help output alone is sufficient to consider Help & Manual a serious player in its market. Add to this its capability to produce customised printed documentation with running headers, support for page numbers in cross-references, and a range of other professional documentation features, and Help & Manual looks good value at its relatively low price point compared with its competitors.
Content is authored and stored in Help & Manual's own flavour of XML that defines elements including <para> and <list> and enables style names to be stored as attributes of these elements. The formatting associated with these styles is stored, again in XML format, within the project (.hmxp)file. The fact that content is not merely stored as XHTML gives Help & Manual an added flexibility to transform its content to a range of different output formats. However, it is arguably less semantically rich than a mark-up system such as DITA, which defines a wider range of standard elements for different types of information (such as <step> and <example>).
Help & Manual can publish to a range of different output types. It is particularly strong in the area of Microsoft Help formats, and is able to produce WinHelp, HTML Help, and Visual Studio Help (sometimes known as Microsoft Help 2). Other useful output types include WebHelp (cross-platform Help), Adobe PDF, Word, and e-books.
Help & Manual is also capable for importing information from other formats. Although it does not import Microsoft Word documents directly, Help & Manual does a good job of importing Rich Text Format (RTF) files. Since any Word document can be easily saved as RTF, this means that it is possible to bring content from Word into Help & Manual — however, it does require the additional step of saving to RTF from Word, which can be a little irritating if you have many documents to import. Styles are converted from the RTF document into Help & Manual, but you do not have the ability to explicitly map RTF styles to existing styles within the project. FrameMakers users should note that Help & Manual cannot import from or publish to the FrameMaker format.
Help & Manual's user interface in detail
EC Software has decided to implement a Ribbon-based interface, as pioneered in Microsoft Office 2007. Using Help & Manual 5 was my first experience of such an interface, and I must say that I was pleasantly surprised by its ease of use. It makes certain features more discoverable and easier to access, and overall seems to reduce the number of clicks required to complete a range of standard authoring tasks.
Figure 1: Help & Manual user interface
Figure 1 shows the user interface. The Ribbon itself (A) is supplemented by the Application Button (B) and the customisable Quick Access toolbar (C), both of which provide direct access to the most frequently used commands. Information about the current project is displayed in the Project Explorer pane (D), which by default is docked on the left-hand side of the Help & Manual window. The remainder of the window is occupied by the Editor (E), a WYSIWYG editing environment that allows you to display and edit one topic at a time. The limitation of only being able to display a single topic is compensated by the ease with which it is possible to navigate between topics using a range of functions and methods including Back and Forward, and selecting from either the table of contents or index.
It's worth mentioning Help & Manual's excellent support for keyboard shortcuts, which I know is a very important issue for many users. You are able to assign your own choice of key combination to any command, and can even define shortcuts for applying specific styles. In addition to this, when you press the Alt key, all of the available options are labelled with a shortcut key, so that it is very easy to navigate the entire user interface without the use of a mouse.
Overall, the user interface is one of the best designed that I have seen for this type of tool. It is professional and modern without being overly complex, and for me achieves precisely the right balance of flexibility, power, and ease of use.
I always like to mention the Help system when I review this type of product, since it should really provide a showcase of what is possible with the product. I was not disappointed by the Help for Help & Manual (shown in Figure 2). Even though it uses the rather unfashionable HTML Help format, it takes full advantage of the best aspects of this format and adds a number of innovative navigation features such as breadcrumbs and topic directories (a drop-down menu providing direct access to key sections within a topic). More importantly, the content is of a very high standard: well organised, clearly written and presented, and with a good balance of task-oriented and reference information. I like the fact that many of the more extensive topics use DHTML effects to present a series of options that can be clicked to reveal the associated detailed information -- there is even an "Expand/collapse all hidden text" button, which is particularly useful if you want to quickly scan all the text in a topic.
Figure 2: Help & Manual's own Help system
Project structure and file types
Apart from referenced images (such as screenshots and icons) and baggage files, the content of a Help & Manual project is stored entirely in XML format. Each topic is stored as an individual xml file, and all the topics are held within a Topics folder. The table of contents is stored in its own separate XML file within a Maps folder. The remainder of the project's data (including styles, window definitions, search settings, and HTML templates) are stored within a single project (.hmxp) file at the root level of the project folder. Figure 3 shows the overall folder and file structure of a Help & Manual project.
Figure 3: Folder structure of a Help & Manual project
When you first create a new Help & Manual project, you have the option of combining all of these files into a single compressed ZIP archive with a .hmxz extension. This is neater and takes up less disk space, but has the disadvantage that it does not allow multiple authors to work on the same project simultaneously.
As you work on a Help & Manual project, any new topics or changes you make to existing topics are written to the XML files in the Topics folder only when you save the project. At first I found it somewhat disconcerting that my content was being held in some unspecified temporary location until then, and it does mean that if you edit several topics without saving, you run the risk of losing all your work in the event of a computer crash. You can, however, reduce this risk by configuring Help & Manual to save all your files automatically at specified time intervals.
Publishing options
As mentioned previously, Help & Manual is able to publish to a number of different types of output. At publishing time, Help & Manual's XML-based topics and style information is transformed to the appropriate format. For example, for WebHelp and HTML Help the topics are transformed to XHTML and the style information is converted to CSS. This process appears to be highly efficient and streamlined as publishing times compare very favourably with other tools I have used.
WebHelp
Help & Manual's cross-platform output format compares favourably with that of other Help authoring tools. It includes most of the standard features of a Help system including tri-pane layout, expanding/collapsing table of contents, index, and search. However, it does not support some specialist Microsoft Help functions such as ALinks (keyword-driven one-to-many links that can help reduce maintenance). Search is an increasingly critical feature these days, and Help & Manual's WebHelp search facility is more than up to the job. Based on a cut-down version of the Zoom Search Engine it shows context in search results (like the way that Google display search results), highlights search terms, supports wildcards, and provides the option to match any or all search words (effectively the choice between Boolean OR or AND).
True to its name, Help & Manual provides a top notch range of features for customising the output format that most authors now use for delivering manuals: Adobe PDF. These features include the ability to configure all the formatting properties of its styles for print output, and an option to insert destination page numbers (known as "Page Referrers") into cross references.
A separate tool called the Print Manual Designer is provided. This enables you to set up the layouts for various types of pages including cover, title page, table of contents, foreword, chapter titles, and topics. It is a powerful and complex tool in its own right, and the process of customising the print layout to your own specific requirements should not be under-estimated. However, it is normally a "one-off" task; having been set up once, all the settings are saved to a Print Manual Template that can be re-used by all future projects.
Help & Manual is the only Help authoring tool I have come across that provides a true "print" output by enabling you to print directly from the project to your printer. As with the PDF output, Help & Manual enables you to specify the layout of the printed output by selecting the desired Print Manual Template. It also offers the option of including Page Referrers.
Basic Help authoring tasks
Creating topics
With some Help authoring tools, the normal workflow is to create a set of topics and then to organise them into a table of contents. Help & Manual is a little different: the normal way to create a topic is to insert a new topic into a specific location within the table of contents. Thus, you are encouraged to consider the structure of your Help system as you create your topics. You do have the option to insert new topics into the Topic Files section of the Project Explorer, which means that a table of contents entry is not created for the new topic. This is useful in the case of pop-up topics, topics that you intend to use as snippets, and other topics that for one reason or another you don't want to include in the table of contents.
You can quickly create multiple topics simultaneously simply by typing as many topic names as you require in the Insert new Topic or Chapter dialog (see Figure 4 for an example). This streamlines the creation process and is an innovation that I have not seen in any other competing tool.
Figure 4: Four new topics being created simultaneously
Topics can be viewed into three different ways by choosing from the following three tabs at the bottom of each topic:
- Page Editor - a WYSIWYG view of the topic that enables content to be inserted and edited
- XML Source - a view of the underlying XML code. You can edit in this view if you choose to, but you must ensure that you enter well-formed and valid XML
- Topic Options - this view enables you to enter metadata for the topic (including title, keywords, and status) and to override the values of specific variables within the current topic
I like the fact that the topic options are available on a tab alongside the topic content as this makes them very easy and intuitive to access.
Indexing
Indexing can be done using the Topic Options tab for individual topics and by using the special Index Tool that lists all the keywords for the project in alphabetical order. This means that you are easily able to view your keywords both from the topic perspective (what keywords does this topic have?) and the user's perspective (what topics will this keyword result in?). You can index in two distinct ways:
- By typing keywords into the Keywords section of the Topic Options tab. I would have liked an autocomplete feature (based on previously entered keywords) here, or the ability to drag keywords in from the Index Tool.
- By adding new keywords into the Index Tool, and then associating them with the appropriate topics using the Edit Keyword dialog.
These two different methods are both useful and are each suited to different phases of the indexing process.
Links and popups
Help & Manual makes it extremely easy to insert hyperlinks to other topics or to web-based resources. You have the option of using the Insert Hyperlink dialog (shown in Figure 5) or of simply dragging the target topic from the Project Explorer to the required location of the link. Help & Manual treats popups in a special way that, again, I have not come across in any other tool. A topic can be defined as a popup topic by setting its Topic Class (within Topic Options) to "Popup". As a result of doing this, any hyperlinks to the topic are automatically implemented as popup links. I think this approach works well since it makes sense to ensure that certain types of topics (such as definitions or captions) always open as popups. The author no longer needs to remember to create a special type of hyperlink.
Figure 5: Insert Hyperlink dialog
One feature I miss is the ability to insert links from "chapter-level" topics to "child" topics automatically at publishing time. This is provided by other competing authoring tools, and has the advantage of saving time and making the maintenance of "chapter-level" topics much easier. I would like to see this option in a future version of Help & Manual.
Support for Styles
When I reviewed Help & Manual version 4 back in 2006 for the WritersUA website (see Review of Help & Manual 4), the concept of styles for topic formatting had only just been introduced into the product. They are now a core feature of version 5, and (as with any other authoring tool that supports styles) should always be used in preference to inline formatting. Help & Manual has two distinct types of styles that can be used for formatting text content, Paragraph and Text. The difference between these two types is that, whereas Paragraph styles can contain both font and paragraph settings, Text styles contain only font settings. Somewhat confusingly, Paragraph styles can also be used as Text styles by applying them to a highlighted piece of text within a paragraph rather than to the paragraph itself. The final formatting of any given piece of text is actually a result of the combination of the Paragraph style and the Text style applied to it, with the font formatting of the Text style over-riding the font formatting of the Paragraph style. This sounds complicated, but it is actually entirely logical and also mimics the way that Paragraph and Character styles work in Microsoft Word.
Within the XML code for a topic, the Paragraph style of a text paragraph is stored in the "styleclass" attribute for the <para> element, and the Text styles are stored in the "styleclass" attribute of the <text> element. For example, the following code shows a paragraph with a Paragraph style of "Note" where a button name has been assigned a Text style of "UI":
<para styleclass="Note"><text styleclass="Note" translate="true">Don't forget to click </text><text styleclass="UI" translate="true">Save</text><text styleclass="Note" translate="true"> before closing</text></para>
The formatting of the styles can be defined and edited using the Edit Styles dialog (see Figure 6) and the settings are stored within the project file (.hmxp) rather than in a dedicated style sheet. Using the Copy Style From... control, Help & Manual enables you to copy styles from one project into another to ensure consistency. You need to be aware, however, that the current styles are entirely lost when importing styles from another project — it is not possible to supplement the existing styles by import.
Figure 6: Edit Styles dialog
Information re-use
Help & Manual has a range of features that enable content and presentation settings to be re-used both within a project and across multiple projects. This has significant benefits including reduced maintenance time and effort, lower translation costs, and greater presentation consistency. Unlike other authoring tools that require all resources used by a project to be contained within the project's own folder, Help & Manual allows you to place a number of key file types including images, snippets, templates and skins in an external folder that can be referenced from any number of different projects. This means, for example, that if you edit a screenshot or icon that is used by multiple Help & Manual projects, you don't need to copy the changed file into each of the individual projects.
Snippets
Snippets are an increasingly common feature of modern Help authoring tools, and they enable you to re-use chunks of content in multiple topics while still maintaining them in a single location. Help & Manual's snippet support is very flexible: if you want to re-use a chunk of content that is within the current project, then you can simply use a topic as a snippet by inserting it (by reference) within another topic. To support this technique, it makes sense to create a number of topics whose sole purpose is to be used as snippets in other topics. If you need to share snippets across multiple projects then you can save them as XML files in an external folder and insert them by reference within topics in any project.
Variables
Help & Manual also supports variables, which are short pieces of text that can be stored and re-used. It makes available a large number of global predefined variables including project title, author, copyright statement and date, and also enables you to add your own user-defined variables. This is very useful, for example, for referencing product names that are liable to change at the whim of the Marketing department! An added twist provided by Help & Manual is the fact that the values of variables can be redefined either at the topic level (within the Topic Options) or more usefully by applying a skin at publishing time. This means that it is very easy to create a customised version of your Help system for a specific vertical market or customer that requires some of the terminology and naming to be changed.
Modular Help
Help & Manual has always provided exceptional support for modular Help. A modular Help system consists of multiple Help projects that can be edited separately but published as though they were a single project. This is achieved by merging the projects either at run time (where the published files for the individual projects remain separate) or at publishing time (where a single set of published files is generated). Either way, the resulting files appear to the user to be a coherent Help system with a single unified tables of contents, index, and search facility. The advantages of constructing Help systems in this way are that the individual component projects can be worked on independently, and that you can easily distribute different versions of your Help simply by including or excluding individual modules in your distribution package.
Skins and templates
I have singled out skins and templates for a particular mention because they are at the core of Help & Manual's strategy of enabling multiple Help projects to be controlled by a shared set of properties and settings held in a central location.
Although I have already mentioned skins, I have yet done justice to their potential power. In addition to providing the ability to override the values of variables, they also store text formatting styles, table styles, window settings, and a range of other settings. In fact, you can think of a skin as having all the properties of a Help & Manual project but without the topic content. Skins can be applied when you publish to HTML-based output, and they effectively enable you to transform your published Help to a complete pre-designed layout with a single click. You can even use conditions to select the specific properties of a skin that you wish to apply, and if you use the command line publishing interface you can combine settings from multiple skins. This makes it very easy to achieve a highly professional and consistent look-and-feel for all of your Help systems.
HTML templates are another powerful feature of Help & Manual that can save time and enhance consistency. They are the equivalent of what are called "Master Pages" in other Help authoring tools, and enable you to add a standard piece of content at the top and bottom of each topic. This can be useful for adding breadcrumbs (a special predefined variable is provided for this purpose) or copyright statements to topics. HTML templates can also be used to add Next and Previous browse controls to topics, and to specify background colours for the header and main sections of your topics. HTML templates are stored within the project, but their settings can be overridden by a correspondingly-named HTML template defined within a skin that is applied at publishing time.
What I have described in this section may sound rather complex and challenging — but it is possible to keep things very simple in Help & Manual by taking advantage of all the default settings and predefined skins. However, if you choose to explore the options for customising HTML templates and skins, then you'll find a surprising level of power and flexibility is available.
Other features
Screen capture and image editor
Help & Manual includes an integrated screen capture facility. It has the same set of features as EC Software's standalone product TNT Screen Capture (which I have reviewed, and enables you to created polished looking images with a range of different edge effects. Help & Manual users also have the benefit of a vector-based graphics editor called Impict that is bundled with the product. Using this tool you can add callouts, highlights, and a range of other shapes and effects to your images. And by storing your images in the native Impict file format that supports layers, you can easily edit or remove captions and other effects if required in the future. All in all, the combination of these screen capture and image editing facilities means that you are unlikely to need any third-party graphics tools for your Help development.
Togglers
Many Help systems these days use Dynamic HTML (DHTML) Effects to hide content and reveal it only in response to clicking a link. This can be a very useful technique for reducing the length of topics by and creating information "layers" that address the needs of different users. Help & Manual provides great support for this, and even enables you to create a "Expand/collapse all hidden text" control that users can click to show or hide all the hidden information. This can be easily added to multiple topics either by using an HTML template or by applying a skin.
Reports
Through its built-in Report tool, Help & Manual enables you to print a range of different reports of varying detail on all of your topics. This can be very useful for tracking the progress of a project and also for providing project management data and reports to management. A nice little added touch is that, when you open a project you have the option of displaying a visual representation of the recent changes that have been made to topics in the project (see Figure 7).
Figure 7: Recent changes displayed at start-up
Multi-author support
In environments where multiple authors may be required to collaborate on a single Help project, support for concurrent authoring is a critical consideration. Unusually, Help & Manual supports multi-user editing directly "out of the box" — all you have to do is to store the project on a shared network drive, and Help & Manual will prevent two users from editing the same topic simultaneously. If, however, you require remote editing or the ability to store a complete version history of your project, then you do have the option of linking a Help & Manual project to a Version Control System (VCS) repository and having the VCS handle all multi-user access. Controls for the VCS are provided within Help & Manual so that operations such as check in and check out can be completed without leaving the Help & Manual user interface. Help & Manual will work with Microsoft Visual SourceSafe and other VSS-compatible version control systems as long as they implement the Microsoft Source Code Control Application Programming Interface (SCCAPI) in exactly the same way as Microsoft in Visual SourceSafe.
Summary
Help & Manual is a remarkably full-featured Help authoring tool that can also produce printed documentation to a professional standard. Its workflow and selection of features demonstrate a thorough understanding of the needs of today's user assistance professionals. On the negative side, if FrameMaker is an important part of your documentation development workflow then Help & Manual is probably not the tool for you because of its inability to import FrameMaker content. However, for many authors its support for sharing resources and settings across multiple projects make Help & Manual an attractive option, providing as it does a powerful mechanism for streamlining development, minimising maintenance effort, and ensuring consistency.
Contact:
For information about how we can help you with user assistance or eLearning, please do any of the following:
- Complete an Online Enquiry Form
- Send an email to info@uaeurope.com.
- Call +44 (0)844 504 2521
