Creating Modular Help

We're often asked how to create modular help, and the approach that you should take depends largely on just how modular your help is...

What is Modular Help?

Essentially, a modular help system merges a number of individual help files into one combined system. Depending exactly on the approach you take, each module is (or can be) published as an independent help file, and another master file is used to pull (or merge) these files together.

Let's explore two different methods you can use:

1) Using Books inside Books

Sub-books provide an easy method of achieving a modular documentation approach.

For example, let's say you have two different products, Product A and Product B. You release three different configurations of these products:

1. Module A only.
2. Module B only.
3. Module A and Module B.

Using sub-books, you make three Books (one for each configuration).

When you update a topic, it is updated in each Book. Author-it automatically includes hyperlinks from A to B, and B to A, but only if A and B both exist in the same Book.

This approach works well when you only have two or three modules, but what happens when you have many? The more modules you have, the more possible combinations there are, and as such this approach can become very difficult to manage. Let's say for example, that you now have four different products: A, B, C and D. This gives you 14 possible deliverables: A, B, C, D, A+B, A+C, A+D, B+C, B+D, C+D, A+B+C, A+B+D, B+C+D, A+B+C+D.

Now how about if you have 20 products? Or 200?...

2) Using a Multi Helpfile TOC and Index

This approach uses what many people consider to be "true" modular help and is ideal when you have a variety of different "mix and match" modules. Your customers may or may not have all the help files, depending on the modules they purchase, so each customer needs different help files.

Rather than having to create a book for each possible combination, the individual files are distributed separately along with one master file that pulls these together at runtime. The helpfiles appear as one help system to the end user with the navigation controls (Contents, Index, and Full Text Search) of the various help files displaying as one seamless integrated system within the Help Viewer. Only those help files found on the end users system are included in the results they see.

To Create a Multi Helpfile:

1. Create a book for each individual module - as many books as required.

   In this example we've created one for Module A, Module B, and Module C:

   

2. Create a master book and include a TOC and Index object in the master book. You can include your standard content such as copyright or legal notices, an introduction section and so on, directly in the master book, or you can create another separate book with this content.

   

   Note: The books for the individual modules can all share a common TOC and Index, but the TOC and Index used by the master book must be unique and not used elsewhere - otherwise you'll find you get some rather "interesting" results when you publish…

3. Open the TOC object used by the master book and under the WinHelp tab, right click in the Create multi-helpfile contents from: pane and choose Add. (Note that the WinHelp tab controls a number of the settings for the various Online Help formats - not just the Winhelp). Navigate to the book/s you want to add - in this case we've added Module A, Module B, Module C, etc.

   Note: Include all books that make up your product set here. Remember only those help files found on the end users system are included in the final file that they see.

   

4. Open the Index object used by the master book and repeat the steps above to add the books to the Index
5. Publish all the books to either WinHelp or HTML Help, and distribute the master file and whichever individual files are required.

   Important: Ensure all files are distributed in the same folder. Only those files that are in the same folder are shown in the TOC, Index, and Search. This means that if the end users don't have the help file for module X, module X content won't display when they view the master.

6. Open the master help file. Voila! The Master Book is now the merged file - the TOC shows all of the topics, the index shows all of the topics and the search works across all the files...

   

Because the master file includes all possible files, if one of the individual module books is updated (or later "purchased") you just need to send the new/updated help file for that module. When you view the master, the changes are shown automatically...