The Reasons for Merging Help

What's covered?

The reasons you might want to consider using merged help. The reasons apply equally to merged WebHelp (Classic), merged Responsive/Frameless help and merged Microsoft HTML help (CHMs).

See Merged_Help for further merged help information.

Introduction

First, what is merged help? It is simply the output from a number of Adobe RoboHelp projects merged so that to the user it looks the same as the output from a single project.

The first Table of Contents in Figure 1 is from merged WebHelp. How can you tell? You cannot - that's the point! The first TOC in the image is a combination of the Tables Of Contents from a number of projects. Then two of them are shown separately. As you can see, in the merged TOC, the books are exactly the same as from the individual projects.

Tables of contents from multiple projects are merged with results transparent to the user.

It's the same with the index, the search and the glossary. You can also create links between topics in different projects.

Merged help comprises the outputs from a parent and any number of child projects (master and subprojects, if you prefer). The beauty of merged help is that you can supply all or any of the outputs from the child projects. When the parent opens, it looks to see which children it can see; the parent and those children are then presented as one integrated help system. It is seamless to the user.

There are three key reasons for using merged help:

1. Creating different versions of the output
2. More manageable projects
3. Multi-authoring without source control.

Different versions

You might want to produce different outputs for many reasons. For example:

Suppose your company produces software that is available with different add-on modules. This is an area where two schools of thought exist. One says you keep it simple and only supply the help a particular customer requires for the modules they use. The other says you supply all the help, but make it clear where functions only exist within a particular module. That way, if the users don't have the module they need, when they see it in the help and learn of its existence, they may buy it. If you decide you only want to supply help for the core product and the supplied modules, then merged help could be your solution.

You simply generate all the outputs and then install just those that you want the customer to see. Obviously, you have to be careful with cross-project links if you do not deliver all the outputs.

More manageable projects

This is the key reason I started using merged help. When I joined a company I worked for, they were producing WebHelp using RoboHelp for Word with all the content in one document. After clicking to open the project, we didn't go off to make the coffee, we went off to make it and drink it! Opening took around twenty minutes. With about 10,000 topics at that time and all of them in one document, that was hardly surprising. It was also risky.

The first thing I did was persuade management that RoboHelp HTML with separate topics was much safer, and more logical given that our output was WebHelp. It still took a little while to open the single project, but it was nothing compared to what it had been. Then along came RoboHelp X3, which was the first version to enable merged WebHelp to be produced without needing RoboHelp Server (or RoboEngine as it was then). I took a copy of the project and trashed half the content to see what difference it made to opening, and it proved to be worthwhile. A look at the content indicated that I would end up with two projects of around four thousand topics each, plus a number of smaller projects. That was a level that made a noticeable difference when opening and working with the project, so I decided to try it. It was quite an effort splitting the content out into separate projects, as there were many links between topics that were going to be in separate projects. However, some careful find-and-replace operations dealt with changing the paths for the links.

Our customers get all the outputs and have never been aware of the change. Combined with the next reason, it was a decision I have never regretted.

Multi-authoring without source control

Coming up to a new release, it can be necessary for more than one author to be working on the help. With a single project, that is not possible unless source control is in use. Because merged help comprises a number of projects, it is possible for us to work on different areas.

I have created a setup whereby we each take a copy of all the projects, but any one person only works on the projects to which he or she has been specifically assigned. By having all the projects, they can create cross-project links. When the work is done, I bring it all back together. Quite simply, if Author 1 has worked on Projects 1 and 2, I delete the old versions from my master copy of the setup and copy in the new versions. From Author 2, I will take Projects 3 and 4. Then I generate the new outputs and deliver them to development.

You have to be very methodical and take backups, but it really is that simple. See the menu for articles on creating merged help.