Re: Multi-file Winhelp projects

[Deborah Meltzer <deborah -at- STARQUEST -dot- COM>]

There are two ways that I know of to tackle this: the first uses multiple
help files accessed from one .cnt file; the second is more cumbersome and is
the method I used before some of the newer technology arrived, and uses one
source file that contains all of the topics for all of the versions. There
could be a third method, which would be to create different "topic" .rtf
files for the differing functionality and select specific ones to import
into your project file and then compile into one help file. In addition,
some authoring tools allow you to import compiled help files and then
recompile into one help file; using a tool like that, you COULD actually
implement your description of compiling several different help files into one.

I think the first method is simpler and more efficient, but I only know
about it in theory because by the time I'd moved on to win95 help files, I
already had my system in place.

I believe there is a better way to implement the first method using a macro
which enables one .cnt file to selectively choose which help files to call
for each version (thus eliminating the need to create multiple .cnt files),
but because this has not been a current need, I haven't researched how to do
this.

First method:
1. create your multiple help files
2. create a different .cnt file for each of the versions you will be shipping
3. include the appropriate .cnt and help files for each version you ship

Each .cnt file will contain links to only those help files you want the user
to see. You need to pay careful attention of course to how you are linking
the included files so that they do not point to "ghost" files that have not
been included.

Second method:
I'd recommend doing it this way if you have a strong desire to have one
source file rather than separate, multiple files (for example, your company
may want to ship only one .cnt and one .hlp instead of one .cnt and multiple
.hlp's).)

1. create one source file containing all of the topics for all versions
2. select the topics you want to compile
3. compile the help file for each version
4. create (or edit from a copy of the existing) .cnt files for each version
to point to correct topics

Of course, as in method one (but probably even more here) this involves
careful attention to how you are linking the various topics. Depending on
the complexity of your project, this can become quite challenging. For
example, Customer A may require links in the Functionality A topic to the
Functionality C topic, but Customer B requires links from the Functionality
A topic to the Functionality B topic (and definitely NOT to the
Functionality C topic).

I brainstormed numerous ways to tackle this problem attempting to retain one
source, and I don't by any means believe I came up with the most brilliant
solution in the timeframe I had to work within. I finally resorted to
creating different copies of the same topics, each containing customized
information for each of the vendors. This did not create as much redundancy
during future edits as it might seem; because most of the text was
identical, I could usually cut and paste changes between the same topics
quickly. Not as elegant and clean as performing each edit one time in one
topic, but not too grueling either.

In Forehelp I renamed each customized topic's *context name* so that I could
internally differentiate it from the others, but retained the same *topic
name* to display in the index. (I don't know if Doc-to-Help gives you the
ability to name the context name, which is not the same thing as the context
id#.) For example, I named each customized topic "Licensing" so that the
text "Licensing" would display in the index list, no matter which of the
topics I'd compiled for a particular version of the help file. But
internally I differentiated them by naming the context names, respectively,
"Licensing1", "Licensing2", Licensing3".

Selecting specific topics to compile for each version of a help file is a
very easy thing to do in Forehelp and I would imagine this is true for other
authoring tools as well, but I might be off base about that.

In any case, hope this helps. If you're interested in finding out more about
the macro mentioned for Method One, let me know off the list and I'll try to
locate the reference to it I saw in another tech writing list. Or perhaps
someone on this list knows what I'm referring to?

Deborah

At 04:28 PM 1/14/97 -0500, Brett Peruzzi wrote:
>     Techwhirlers:
>
>     One of my writers is working on a Winhelp project for an application
>     that may be customized for specific clients. She and the developer
>     have been speculating on how best to produce the customized help
>     without a lot of redundant effort.
>
>     What they're considering is creating separate help files for each area
>     of product functionality, so they can choose which help files match
>     the product features the specific client needs. These separate help
>     files will then be combined and compiled together to produce a single
>     help file. Kind of an object-oriented approach, with an emphasis on
>     information re-usability.
>
>     Has anyone done this, and if you have, what advice can you offer?
>     We're using Doc-to-Help 1.6 as our authoring tool, by the way.
>
>     Thanks,
>
>     Brett Peruzzi
>     Documentation Manager
>     First Data Investor Services Group
>     Boston, MA
>     Brett -dot- Peruzzi -at- fdc-invest -dot- com
>
> 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
>
>
=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=
Deborah Meltzer
StarQuest Software, Inc.
email: deborah -at- starquest -dot- com
voice: 510/704-2554
=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=

 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