Re: Writing Help for a modular application

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

>      Hi,
>      I'm having trouble figuring out how to create a multiple-Help
> project
>      system for an application that has several modules that may or
> may not
>      all be installed -- and I really could use your assistance.
>
>      Here's the problem: When the user installs only certain pieces,
> we
>      would like the online Help NOT to include Help topics about the
> pieces
>      he chose NOT to install. Otherwise, the user might read about
> them,
>      try to find the features, get mad when he can't and call tech
> support.
>
>      The only way I've heard one can achieve this is by creating a
>      Master.cnt file. But this won't work for us UNLESS we plan never
> to
>      edit the files again, because every time you recompile you lose
> all
>      the custom coding that makes the Master.cnt work.
>
>      Beth Kane
>      bkane -at- artisoft -dot- com
>
>
Beth;

My help is all modular.  Each application module has a separate help
file and a separate contents file.  Each product or variation of the
product has a project file listing only the source files and build tags
for the applicable topics.  I create separate HPJ files (with
appropriate build tag inclusions) to compile help for applications that
use the full functionality and for applications that use partial
functionality.  This supports the use of single-source topics.  Build
tags make the distinction as to whether a topic is included in a
partial-functionality version of the help.  To recompile a help for an
application module that does not include full functionality, I either
drop the build tags (from the HPJ) denoting the partial-functionality
topics or insert Exclusion tags to block the partial-functionality
topics.

I rarely use direct jumps.  Instead, I use ALinks.  As a result, links
that exist in one help configuration are not broken when excluded in
another configuration.

Each product has a master contents file.  The master contents file is
just a shell.  Most entries in the master contents files are include
statements to the individual module content files.  The only hard-coded
topic links in the master contents files are to topics that are specific
to the product or product variation (such as introductions).  The master
contents file also allows linking between modular help files so that the
index, full-text search, and A-Links span across modules.  [To
facilitate creating and maintaining multiple contents file,  I have
written some macros.  They create topic entries from headings and
TopicID endnotes in the RTF files.  I then paste the topic entries into
an empty contents file.]

I circumvent multiple link listings (topic titles appearing more than
once) while maintaining a single-entry index by varying my Alink terms
in similar topics but maintaining consistent KLink terms.  This
methodology allows me to quickly add to an application module's help
(should functionality be added or expanded) without much editing of the
RTF files (and producing a ripple effect on other help).

Context sensitivity is also an area that must be designed carefully in
modular help.  An application module can only reference one help file;
however, the module may be used in many applications.  Therefore, an
application module has an independent help file which travels with the
application module regardless of how the product is packaged.

Mike Wing

> Michael Wing (mailto:mjwing -at- ingr -dot- com)
> Principal Technical Writer
> Intergraph Corporation; Huntsville, Alabama
> http://www.ingr.com/iss/products/mapping/
> (205) 730-7250
>
> "But examine everything carefully; hold fast to that which is good"
> -- Paul (1 TH 5:21)

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html