If you want to get the full benefits from modular projects you need to do some planning. Module divisions should be logical rather than arbitrary. You must break your project up into modules in a way that increases your flexibility, and you need to plan ahead to make sure that you take any possible future changes into account. You also need to think very carefully about links between modules and make sure that any links you create will not create problems for you later.
Planning for future modular help systems
Even if you are not using modular projects now it is a good idea to plan ahead just in case you decide to modularize your projects in the future. In particular, you should always use topic ID naming schemes that will enable you to combine projects at a later date without creating ID conflicts. Then you always have the freedom to switch to runtime merging if you want, and your projects will also have a better and more logical structure that is easier to manage in the long run. See Managing IDs and context numbers for instructions on how to avoid duplicates.
Be clear about which module is your master module:
Even though every Help+Manual project can contain as many modules as you like, you should always manage each modular help system with one master project. Otherwise you will go crazy trying to keep track of everything and mistakes are almost guaranteed sooner or later. You can reuse modules in different modular help systems, but then they should be completely separate systems with their own master modules.
Don't nest your modules too deeply
Sub-modules can also contain their own sub-modules and there are no physical limits on how far you can nest sub-modules. However, it is best to make cautious use of this capability because it is easy to lose track of what you are doing. This applies in particular when you are mixing runtime and publish time merging.
It's a good idea to store your child module projects in a clearly-organized directory system without many levels of sub-directories. Even if your project itself has many levels, you will find your project files much easier to access if you store them all on the same level in folders with descriptive names, possibly including level numbers.
Don't create modules unless you really need to
Don't create modules just for the sake of making modules. A single project is always easier to manage, it can be edited by multiple users at the same time (Professional and Floating license versions only) and Help+Manual can manage large projects with ease.
Master modules with and without content
The master module can have content of its own or you can use it as an empty framework for the sub-modules. If the master has content then the common components of your documentation that are always included should be in the master module.
If you put as much as possible in separate modules the master module only needs to be edited by the person responsible for doing the final publish, and this can be an advantage.
Exception: Runtime-merged CHM modules
In modular HTML Help (CHM) projects in which the child projects are merged in runtime mode, the master project must contain at least one topic and the default topic must be set in the master project. If you don't do this you will get an error opening the main CHM and the indexes of the child CHMs won't be available. (This is caused by uncorrected bugs in the Microsoft HTML Help system.)
Minimize links between modules:
Each module should be as independent and complete in itself as possible. It should contain all the information needed to describe the module of your application that it is built for.
If you are using runtime merging it is particularly important to make sure that the context-sensitive help topics needed by your application are going to be there when the user needs them. It may be necessary to move topics to one of the main modules that is always present. If you don't want to include the topic in the TOC you don't have to, you can create a topic without a TOC entry and link to that.
It is generally advisable to avoid context links across module boundaries, even if you are currently using publish time merging. This will save you a lot of unnecessary work if you ever decide you want to switch to runtime merging.
Links to the master module are never a problem because that is always present, but links between modules and from the master to the child modules should be kept to an absolute minimum. If you must create inter-module links you should make absolutely sure that the target module will always be present when the user runs the help. Alternatively, use A-links to make sure that links to non-existent modules will display a suitable alternative topic.
Always call popup topics directly
Calls to CHM popup topics are not routed from the master module to the child modules. If you call popup topics in HTML Help CHM files from your application you must always make the popup calls directly to the help file containing the popup topic, not to the master file. (This only applies for runtime merging, of course – in publish time merging there is always only one help file you can make calls to.)
Take steps to avoid duplicate topic IDs and context numbers:
In publish time merging duplicate topic IDs and help context numbers in modules will cause link failures and other errors in your help files. Help+Manual can only prevent duplicates within a single project so you have to take steps to prevent duplicates in your modules yourself. For details see Managing IDs and context numbers in Working with Modular Help Systems.
Always place all your output files in the same directory
This is essential for runtime-merged CHM projects. The Microsoft HTML Help viewer in particular has some annoying bugs that make it almost impossible to call files from the help that are not in the same directory as the help file. Even if links to other directories seem to work on your test computer they will fail on very many users' computers, so don't use them.
Don't worry about the whys and wherefores, just always put all your help files and any external files you need to call in the same directory. That is the only way to avoid problems and have a help system that always works.
See also:
