A modular help system is a help system that consists of multiple help projects that can be edited separately but published as though they were a single project. There are also two levels of "modularity": Modular help projects (your project consists of multiple Help+Manual modules) and modular help systems (your output help files also consist of modules).

Modular help projects:

A modular project consists of multiple projects, referred to as "modules", that you edit separately but publish together with the help of a main project referred to as a "master project" or "master module".

You can output a modular project as a single help file, then you are only using authoring modularity, or as multiple help files, then you are also using output modularity.

Authoring modularity gives you practical advantages for managing your projects, output modularity gives you additional flexibility for the configuration of different versions of your help.

Modular help systems:

A modular help system is one that is made of separate modules at "runtime", i.e. when the user is viewing it. Runtime modular help systems are only supported in the Microsoft HTML Help (CHM) format.

A modular CHM help system consist of a "master" CHM module containing the main TOC, which must always be present, and one or more "child" CHM modules, any of which may or may not be present.

If a child CHM module is present at runtime its TOC is merged into the TOC of the master CHM module when the help is viewed. For the user everything looks like a single help file. If the child module is not present its TOC is not included. This process is automatic and depends only on the presence of the child CHM module in the same folder as the master CHM module.

With a little planning you can easily distribute different versions of your CHM-based help for different product versions just by including or excluding individual modules in your distribution package.

See Runtime and publish time merging for more details on truly modular projects.

Multiple TOCs

You can combine alternative TOCs with modular projects. For example, you could create a TOC that contains references to a completely different set modules in a different order and combined with different topics and chapters.

Linked snippets are not modules

In addition to modular help systems Help+Manual also allows you to include individual topic files and chapters from other projects in your current project as linked snippets. This blurs the distinction between modular and non-modular projects slightly.

It is important to understand that true modular help systems are only possible when entire projects are used as modules. When you insert a topic or chapter from another project it becomes part of the current module when you publish. Such topics and chapters cannot be handled as separate modules in published modular help systems, even in HTML Help.

Why use modular help systems?

There are a number of very good reasons for using modular help systems:

Create different versions without editing:

In HTML Help you can create genuinely modular help systems (see above) in which you can include and exclude entire sections of the help simply by including and excluding help files from your distribution package. You must always include the master file but if a child file is not found its contents are simply excluded from the TOC automatically. This is ideal for applications with different versions.

Reusing content efficiently:

You can create "boilerplate" projects for reusable project sections, for example introductions that are always very similar or your product lists or terms and conditions. (Note that in many cases snippets are also an efficient way of doing this.)

More efficient group work:

When you are working on a project in a team you can assign separate modules to each team member. Each author can then work on his or her own modules separately if they do not have access to the central version on the server.

Managing very large projects:

Modularizing your help projects makes large projects easier to manage. Among other things, publishing the smaller child modules on their own is faster and you can check your output more quickly.

Master projects and child projects

A modular project consists of one master project and one or more child projects (which can in turn be master projects containing their own child projects).

Both master projects and child projects are ordinary Help+Manual projects. The only thing that makes them "modular" is the way they are structured: References to the child projects are inserted in the TOC of the master project as single items, in exactly the same way that you insert topics.

It is important to understand that inserting a child project in a master project does not merge the projects physically. They still remain separate projects. They are just managed together.

Editing modules inserted in publish-time merging mode:

•In the Master TOC:
Publish-time merging modules are displayed as part of the master TOC and can be edited directly in the TOC, in the same way as the master project's own topics. (To enable in-place editing you may need to activate this in Configuration > Common Properties > Miscellaneous and then reload your project.)

•In the Merged Projects section:
If you open the Configuration section in the Project Explorer you will find a section called "Merged Projects" right down at the bottom. This gives you direct editing access to the entire contents of the module, including its Configuration settings, project files and so on.

Editing modules inserted in runtime merging mode:

Modules inserted for runtime merging are just placeholders, however. To edit them you need to right-click on the placeholder in the master TOC and select Open Child Project... The project will then be opened as a normal additional project in the Project Explorer.

Publishing modular projects

When you publish the master project it behaves as though it is a single project. The entire TOC of each child project and all the topics it contains is merged into the output. This works in all output formats supported by Help+Manual, but there are differences in how it is handled and the options you have depending on the format you choose:

See also:

Working with Modular Help Systems