Modular Projects

A modular project is necessary when you have a collection of several different output files (and would like to keep them that way) but would like them to appear to the end user as a single output system.

There are four common scenarios necessitating a modular project:

  • Modular Software Your software application is sold as separate modules with the user purchasing one or more modules at a time. Modular output will contain all the output files, but only the appropriate output files will accompany the purchased modules.

  • Large Documentation Sets If you wish, you can chunk information into several small online outputs and create a modular project rather than deploy one large online output system. Smaller projects enable streamlined updating and easier distribution.

  • Online Outputs with Future Projects Planned If you plan to release your online output in stages, you can pre-position placeholders for future online projects before they are released. Instead of distributing the entire online output collection each time you add to the system, you only need to distribute additional online output files. If you didn’t plan for an addition, you can distribute a new hub output file along with the new output files.

  • Documentation Teams Sharing Responsibilities Across One Large Project Modular output can be a solution for a large project with many authors. Each author is assigned one or more projects. The team leader is usually charged with the responsibility of maintaining the hub project and assembling the entire project.

    You may want to check out Doc-To-Help’s Team Authoring capabilities and use those instead. See Team Authoring.

Modular outputs are composed of one hub (or master) project and any number of child projects. The modular system appears to the user as one integrated collection of online output. The contents and index are merged at run time, when the output is opened. Dynamic links are also created at run time.

The following files are distributed to end users. When you are ready for release, these files should be stored in the Redistributables folder of your modular project. See File Organization.

  • Hub project .chm file

  • All child .chm files

  • The entire contents of the hub project NetHelp folder. Since NetHelp is uncompiled HTML Help, the number of files will vary. By default, click on the index.html file to open the output. (This file name can be renamed in the "Default name" field of the Help Targets dialog.)

  • The entire contents of the hub project EclipseHelp folder.

Note When creating a hub project, avoid including spaces in any of the file names. Using spaces in file names will disable the next/previous functionality of the modular output. If your .d2h project file contains spaces, you can fix this without renaming the project by specifying a name with no spaces in the "Base name" field in the Help Targets dialog. See Creating and Deleting Targets.

In order for your modular project to mesh logically, it's important that all the pieces adhere to a set of standards. You may want to create standards for the following:

  • Source and target templates 
  • Styles, and how they are used
  • Help window definitions (each project should use the same Windows)
  • Indexing conventions (keywords and groups)
  • Use of graphics and graphics format
  • Tone and style of writing
  • Map numbering for context-sensitive Help

If you are using a centralized glossary, each project should not have terms in its local glossary; all items should be stored in a central glossary (in the hub project).

Good file organization makes it easier to manage your modular hub project and avoid errors.

Your file system should include:

  • A folder for the entire system

  • A subfolder for the hub project

  • A subfolder for each child help project

  • A subfolder to store the end-user project redistributables

For example:

If your project has multiple authors, it is best to store the project on a network drive.

Following are the primary tasks for working with modular projects:

  • Create Hub Project In modular output, the hub (or master) project ties all of the child projects together. It should be a small project, but can contain information that does not change often (e.g., welcome message, company contact information) if you wish. See Creating a Hub Project.
  • Create Child Project Child projects are tied together with the hub project. There are no special mappings in child projects, just a few settings and other options that need to be handled. You can create as many child projects as needed. See Creating a Child Project .
  • Create Modular Ouptut for Help Viewer Targets The Microsoft Help Viewer (MHV) target is exclusively for integration with the Microsoft Visual Studio 2010 (and above) output (see Output Types). The purpose of a MHV modular project is to combine the tables of contents of multiple projects so that they appear as a single TOC when integrated with Visual Studio 2010 (and above) output. See Creating Modular Output for Microsoft Help Viewer Targets.

Note Modular projects can reference files that are not installed (e.g., Help for a software module the end user has not purchased) and still look seamless. The table of contents and index will simply omit the missing information without displaying error messages. If the user installs the module in the future, the output will be added to the modular system in the proper position.

Note Verify that your software can accommodate context-sensitive calls from multiple HLP or CHM files before creating a modular project. If your software can only accommodate context-sensitive calls from one Help file, you can still create a modular system, but in that case you must place all context-sensitive topics into one Help file.