Review of Help+Manual
A look at the HTML code or PDF properties of any software documentation from a wide variety of manufacturers worldwide reveals something astonishing: a surprisingly high proportion of the documents have been created using an authoring system from Austria: Help+Manual. This review shows the particular strengths of Help+Manual and explains for which scenarios the authoring system is most effective.
Notes: This review was sponsored by the manufacturer of the software. However, the manufacturer did not influence the content of the review. The version tested was version 9.2.
System requirements and installation
Help+Manual runs exclusively under Windows and has no special hardware requirements. It is installed and ready for use within a few minutes.
The user interface language can be set to English, German, and French. However, the program’s very good and detailed online help is only available in English.
Structure of the user interface
The program has a classic Windows interface with a ribbon menu bar (which can be hidden if desired). On the left side, there is the Project Explorer, which holds the entire content and project management. On the right side, there is the Topic Editor for editing the content.
All topics of a project and all settings are accessible with a few clicks via the Project Explorer, without having to find your way through various tabs or palettes first. This makes working with the program easy and efficient. Hardly any other authoring tool makes it possible to browse various topics in such an easy way, for example when searching for a specific section or to make specific changes in multiple topics. Where other content management systems require you to tediously check-out and check in individual modules, and dozens of tabs accumulate in the user interface, Help+Manual requires only a single click. This makes working fun!
If you want to customize your working environment, you can do that, too:
▪Optionally, you can also open multiple topics at the same time.
▪Optionally, you can also edit the topic content and the topic metadata in parallel.
▪Optionally, you can also undock the Project Explorer or the editor with individual topics, freely position them, and move them to a second screen, for example.
Editing content
Help+Manual shields the authors from technical things like XML, HTML, or CSS to a large extent. The basic work with the program is no more complicated than with a classic word processor: writing texts, assigning formats, inserting tables, formulas, graphics, or videos, as well as linking content: it’s all WYSIWYG and drag and drop.
If required, the underlying XML code can also be displayed and edited at any time, but this is almost never required, except for very advanced and special operations.
In practice, having a powerful function for project-wide search and replacement of content to be changed is very important. This is well-supported by Help+Manual. The search results are listed on a separate palette on the right and can then be processed either automatically or manually one after the other.
Also worth mentioning in particular are:
▪a comfortable Index Tool for creating an alphabetical keyword index
▪a clearly arranged Context Tool for assigning numerical IDs for context-sensitive help calls
▪various report functions, including the ability to delete all unused images within a project at the push of a button
▪an integrated screen capture tool that can also record short animated sequences of images
▪the ability to embed images created and edited with the popular screen capture tool Snagit directly as a Snagit file, without having to export the images to a standard format such as PNG or SVG beforehand
▪a Replace Styles feature that enables you to automatically map manual formatting of legacy data to the existing paragraph and character formats of a project
Generating documents
Documents can be generated in different variants and output formats from a project’s database (single source publishing). For each document, it is possible to individually set which content is to be displayed and which content is to be hidden, as well as which layout and design are to be used.
For example, you could generate from a single Help+Manual project:
▪WebHelp for the “Personal Edition” of the described product
▪a PDF manual for the “Personal Edition” of the described product
▪WebHelp for the “Enterprise Edition” of the described product
▪a PDF manual for the “Enterprise Edition” of the described product
▪WebHelp for an OEM variant of the described product, where this WebHelp looks completely different from the WebHelp for the in-house variants
▪a PDF manual for an OEM variant of the described product, where this manual also looks completely different from the manuals for the in-house variants.
All documents originate from the same source and are maintained in a central location. If the documentation needs to be updated later, only the central location in the project needs to be updated. This saves a lot of time and avoids errors.
Help+Manual supports the following output formats:
▪WebHelp (HTML)
▪CHM
▪Word
▪EPUB, MOBI
▪Microsoft Visual Studio Help
▪eWriterHelp
In addition, the system generates header files in different syntax for the context-sensitive connection of an online help system, if required.
The following figure shows an example of a WebHelp generated with Help+Manual using one of the supplied skins without customization:
Special feature eWriterHelp
The eWriterHelp format is a native format as an alternative to the CHM format, which has not been significantly developed by Microsoft in recent years. An eWriterHelp is either directly a Windows executable file (*.exe) or is displayed via its own viewer. The viewer can be installed by software vendors together with an application on a user’s computer. The help itself looks the same to users as a WebHelp, with the only difference being that to display the help, no browser starts separately, but the help appears in a standard program window. An eWriterHelp can be connected to an application in the same context-sensitive way as a WebHelp or a CHM file.
The advantages of an eWriterHelp compared to a WebHelp are:
▪Only one file needs to be delivered and installed on a user’s computer. All individual pages, images, videos, and other files are embedded in this file.
▪The help runs under a defined environment. Thus, the display does not depend on which web browser a customer happens to be using and what settings the user has made in that browser.
Tip: On the manufacturer's website, you can download a free tool called eWriter Creator. You can use this tool to convert even HTML-based online documentation into the eWriterHelp format that was created with authoring systems other than Help+Manual.
Single source publishing
Help+Manual supports single source publishing at all levels:
▪Any number of variants, so-called builds, can be created in a project. By default, there is already one such variant for each output format, i.e. one variant for HTML, one variant for PDF, and so on.
▪Optionally, one or more of these variants can be assigned to a topic as a whole. If this is the case, the topic in question will only appear later in a document if the corresponding variant was also activated for this document when it was generated. Several variants can be combined if necessary. (Example: A document contains all the contents of variants A and HTML, but not the contents of variants B and PDF.) If no variant is assigned to a topic, this topic will always appear in any document.
▪Any content within a topic can also be marked as variant-dependent. This makes it possible, for example, to have a different image in one variant of a document than in another variant of the same document, or to have certain texts differ between the variants or be missing in individual variants. Conditional contents within a topic are distinguished by IF-THEN-ELSE flags, which can even be nested.
▪Finally, at the lowest level, you can use variables. These can dynamically assign individual sentences or sentence fragments when generating a document. Such a variable can contain, for example, the product name, the version number, the publication date, or the title of the current document.
▪If the same content occurs multiple times within a document – for example, a particular warning – this content can be stored centrally as a snippet. It can then be reused as often as required – not as a copy but by reference. If the content has to be changed later, only the centrally stored snippet needs to be edited. All places that use the snippet are then automatically up to date again immediately as well.
▪If several documents generated from a project differ not only in that certain content is missing in individual variants, but also in their structure, each document can be given its own table of contents (TOC). If required, several TOCs can even be nested within each other.
However, it is not possible to nest multiple WebHelp files generated with Help+Manual only at runtime. Thus you cannot create modular online documentation whose content builds up dynamically based on the modules of the described software that are actually installed.
Translation
Projects in Help+Manual are always monolingual. If documentation is required in several languages, a copy of the project must be created for each language and then this copy translated. However, this sounds more complicated than it is, because professional translators usually work with a so-called translation memory system (TMS) – at least that is what they should be using. In combination with a translation memory system, the translation process looks like this:
1You complete the documentation in its original language.
2You make a copy of the project.
3You send the copy of the project to the translator.
4The translator reads the XML files contained in the project copy into their translation memory system and does the translation within the translation memory system. (The translator therefore does not need to have a license of Help+Manual and cannot "break" anything in the data.)
5You receive the translated project back from the translator, open it in Help+Manual, and generate the desired documents in the foreign language.
If you update part of the documentation later, the process repeats itself. However, as the texts translated in the last version are then already available in the translator's translation memory, the translator does not need to retranslate everything, but only the places where something has changed.
Machine translation
As an alternative to the classic translation by a translation agency, you can translate a project yourself in Help+Manual. To help you do this, Help+Manual comes with a special plugin for DeepL. With the help of this plugin, an entire topic can be translated automatically at the push of a button, whereby all formatting and links are fully preserved. You can also store a project-wide glossary to teach DeepL how to translate certain things in your specific context. This greatly improves the quality of machine translation.
The Translation Assistant tool, which is available separately from the manufacturer, goes even one step further than the standard DeepL plug-in. With the Translation Assistant, not only a single topic, but a complete Help+Manual project can be machine translated at the push of a button by DeepL. As it cannot (yet) be assumed that such a translation will be perfect right away, you can then refine the translation manually. If you later update the documentation, the Translation Assistant helps you to have DeepL retranslate only those things that have actually changed. Your manual corrections to the parts that have remained unchanged are retained.
Working in a team
If a Help+Manual project is stored on a network drive, several people can access and work on the project simultaneously. If an author is working on a specific topic, the topic is locked for others during this time.
In addition, Help+Manual can be connected to a version control system if required, which also enables cross-location collaboration on a project. Help+Manual supports Git and Subversion.
To ensure consistency of formats across multiple projects, formats can optionally be managed in a repository separate from individual projects. If a project uses a repository, individual authors in the project can no longer change the format properties.
Each topic can optionally be assigned a specific topic status. When generating documents, all topics whose status is not set to Complete can be excluded if desired.
For the purpose of reviews, Help+Manual can generate a special PDF review file. A person can add comments to this PDF file during proofreading with any PDF reader like they could edit comments to any other PDF file. Once the review is complete, Help+Manual can re-import the review file and authors can conveniently read the review comments and jump directly to the corresponding places in the project.
Versioning
Even without a connection to a version control system, Help+Manual can store a history for each topic, including date, time, and author. This makes it possible to restore an earlier version of a topic at any time. The number of versions of a topic that Help+Manual archives, can be set on a project level. (Note: A new version is archived each time a document is saved. However, as users do not explicitly check in a version, there is no way to annotate such a version.)
Optionally, a project can be linked to a version control system (Git or Subversion). However, the functions within the Help+Manual user interface are limited to Update (Get) and Commit. All other operations have to be done via the version control system itself, if necessary.
Data migration
Help+Manual can import data in the following formats:
▪Word (RTF)
▪Markdown
▪HTML
▪CHM
▪HLP
▪RoboHelp
▪Author-it
▪Visual Studio / Sandcastle Documentation
Based on the headings contained in the documents to be imported, topics can be created automatically during import.
Customization
The individual adaptability of the design of all generated documents is one of the great strengths of Help+Manual. It doesn’t need any special know-how or special tools.
▪Freely configurable paragraph, character, table, and image styles control the appearance of the content. By default, the styles are the same for all output media, but differences between online and print output can be defined for each style if required.
The styles are set up within an easy-to-use Style Designer. It doesn’t require any knowledge of CSS, XSLT, XSL-FO, or similar things. All settings are made via dialogs as in a classic word processing application. The styles can be organized hierarchically, and style properties are inherited by the elements subordinate to an element, which facilitates maintenance.
The Style Designer does not support all the possibilities of CSS by far. For PDF output, the formatting options are limited to the settings available in the Style Designer. For HTML output, any CSS code can be added to the page templates at any time, which makes it possible to also implement special formats.
▪There is a separate tool for creating print layouts: the PDF Manual Designer. There you can design the page templates for each page type in a WYSIWYG interface.
▪Those who prefer to export to Word instead of creating PDF files directly can control the appearance of Word documents using a Word template.
▪The base layout and the design of the navigation of online documentation produced from the system are determined by the skin used during the generation. Depending on how deeply you want to intervene in the settings of a skin, there are two options:
–A number of basic settings can be made via dialogs.
–If you want to go deeper, you can edit, add to, or freely design the HTML code down to the last detail. You can even use the build settings and variables defined in the project within the code, making it possible to implement very sophisticated solutions.
Automation
To save time at work, Help+Manual provides the following functions, among others:
▪assignment of styles via freely definable keyboard shortcuts
Tip: If this is not enough, you can automate further things with a tool like AutoHotkey (open source). This can be used, for example, to add text macros or autocorrection. See AutoHotkey scripts for writing technical documentation.
▪insertion of frequently used special characters from a freely configurable special characters list
▪insertion of frequently used symbols from a freely configurable symbols list
▪command line interface for automated publishing
▪task manager for generating multiple predefined documents in a single operation also via the user interface
Pushing the limits of what is possible
With their built-in functions, authoring systems typically support only a few basic functions in online documentation. Help+Manual, for example, supports expandable and collapsible sections (“dropdowns” or “toggles”) as well as clickable thumbnail images. Sometimes, however, it makes sense to add some other useful features as well, that have long been standard on many modern websites, such as tabs or a sortable table, for instance.
In this respect, Help+Manual is very flexible compared to many other authoring systems and usually tolerates such extensions quite well.
▪The HTML, CSS, and JavaScript code of the page templates can be freely edited. The items added here then appear on every page of a generated online documentation.
▪If you want an object to appear only in a certain topic, you can insert any individual code snippet with HTML, CSS, or JavaScript code into the topic.
Tip: You can find various examples with the required codes on the following page: CSS+JS Code snippets for enhancing online documentation. By the way: These examples all work with Help+Manual, because the website you are currently on was also created with Help+Manual. This alone shows how flexible the output can be customized...
The bottom line
Help+Manual key strengths are its efficiency in work, as well as the almost unlimited customization possibilities of the online documents generated from the system. There is probably no comparable program that can produce professional results so quickly. The range of functions covers all the features that a modern authoring system should provide at a very reasonable price.
The online documentation generated with Help+Manual is technically state-of-the-art. On closer inspection, however, there are a few shortcomings in functionality compared to significantly more expensive authoring systems or even more expensive content delivery platforms. For example, online documentation generated with Help+Manual does not support faceted search, and the search function cannot be enriched with synonyms. On the other hand, the generated online documentation can be so flexibly adapted that a third-party search engine could be used as an alternative to the built-in one.
With PDF output, attractive and professional layouts can be created, even with multiple columns and automatic hyphenation. However, there are a few limitations in detail here as well. For example, page breaks cannot always be optimally controlled down to the last detail at all points. Cross-references just contain a page symbol with the respective page number printed on top, but cannot include any custom text such as “see page” or a similar phrase. If you like to work with marginalia in the print layout, you will not be able to do this with the on-board tools. In this case, however, the alternative is still to output to Microsoft Word and edit the manuals externally. But this ultimately contradicts the idea of automated publishing at the push of a button, which Help+Manual intrinsically supports so wonderfully.
The simple operation of all basic functions can also be mastered by people who do not spend all of their working time with the program. Nevertheless, it is also possible to dive deep into the program if needed, to accomplish even very demanding tasks, and to automate processes to a large extent.
Help+Manual compared to smaller and larger systems
Help+Manual is primarily aimed at individual authors and smaller teams of authors. It is certainly not a substitute for a large and many times more expensive Component Content Management System (CCMS), with which dozens of editors simultaneously manage hundreds of documents in many languages and more than 10 or 20 variants in parallel. However, when taking a close look, even in larger documentation departments, a more comprehensive CCMS is often not necessary at all. It is not uncommon for a large documentation department to have small teams that operate largely independently of one another. Considering each of them separately, an authoring system such as Help+Manual can be a lean and efficient alternative.
At the lower end of the price scale, Help+Manual competes with the tools from the fields of “Dos-as-Code” and “Static Website Generators” (both mostly open source). Compared to these solutions, Help+Manual has the advantages of being easy and fast to install and of being able to generate professionally designed PDF files in addition to HTML. Above all, Help+Manual has all the features that make working with large documents efficient in the long run: conditional content, variant control, link management, etc. These things may not seem to be very important when a document is first created, but they soon can save tons of time and money over the entire life of the documentation. The total cost of documentation is often not in its initial creation but in its many years of updating and maintenance. In this case, a professional tool such as Help+Manual can save many times more money in the long run than a license costs.
Pricing and licensing
Help+Manual is available in a Basic Edition and in a Professional Edition. The main difference between the two editions is that with the Basic Edition projects cannot be saved as XML files, but only in the form of one single compressed project file. This means that all options based on individual XML files – such as team authoring, version control, and translation via a translation memory system – are not available. The Basic Edition also lacks various automation options, such as publishing tasks. On the PDF creation side, the version has no effect, but WebHelp created with the Basic Edition lacks the search function, which greatly affects usability. Ultimately, this means that the Professional Edition is almost always required.
▪Basic Edition: €498,-
▪Professional Edition: €798,-
The licenses are perpetual and include updates for one year.
Manufacturer and licensing options: helpandmanual.com