Re: editable help systems

["Steven Feldberg" <steven -at- icu -dot- com>]

Cathleen McIntosh wrote:

> Is there a way to deliver a help system and let customers edit it via
Word?
> Would they need RoboHelp to to this, e.g. in order to recompile after
edits
> are made? Are any of the auto-generated files in a help project anything
> like a .ini file, or can you use an .ini file with a help project that
would
> allow users to define or select variables in the .doc file?

Earlier this week a reseller of a client's product made the same request
(retroactively in this case -- the Help system has already been built and
distributed; if you are in the development phase of your Help system, then
you have the opportunity to design for "editability"). For what it's worth,
here's what we did:

The first thing was to resolve the policy issues. The firm (that
owned/produced the Help file) decided that they *would* sanction customer
edits to Help and, further, defined a policy to deal with supporting such
customer edits. This has been stated explicitly -- and in writing. Some of
what we addressed included questions like, will *all* customers have access
to the Help source? If not, what criteria will we use? What level of support
will be given to those altering their Help files? Will altered Help files
impact product tech support for end-users on the receiving end of such Help?

Next was to clearly define what it meant for customers to "edit" the Help
system. Customers would be able to:
  * modify text within topics
  * substitute terms in the existing text for customer's preferred terms
globally
  * make *no* architectural changes to the existing help system -- meaning
no addition/deletion of existing help topics and no new links or
modifications to existing links
  * use MS Word to make their changes.

Issue: each customer would have to deal with Help system synchronization on
their own -- meaning that when we distribute updated Help files they'll have
to ignore them, or re-edit them.

The customers I spoke with were happy with these constraints.

(An alternative, of course, is to pass along the RoboHelp source files to
the customer, tell them to purchase RoboHelp, and wish them luck. Not a
stellar idea, but in this make-the-customer-happy-no-matter-what biz
environment, we will do it -- while actively discouraging it.)

Next, we packaged the source files the customer would require. Rather than
supply the raw source directly, we used RoboHelp's (7.0) Help-to-Source tool
to back the source out of the compiled HLPs (our Help system consists of 12
Help files). Help-to-Source is useful because it creates a single RTF file
from the HLP (rather than the dozens of DOCs we authored from); it also
creates a project directory with the other required files, including BMPs,
SHGs, the CNT file, the Map file (HH or whatever you're using), and the
Project file (PRJ). Then we edited the CITATION= and COPYRIGHT= lines in
each PRJ to indicate that the associated HLP has been altered from the
"factory-issued" version. We also included the required RoboHelp DLLs
(RoboEx32.dll and Inetwh32.dll in our case).

Then we packaged up the Microsoft Help Workshop files (including the Help
Compiler). You have to be careful about this, though, because I'm not sure
how the copyright/distribution arrangement for the Help compiler works.
Check with Microsoft to be on the safe side.


From the customers' standpoint, they load the RTF into Word, make their
changes and then compile the Help project. To make that easier, we're
including several Word macros and batch files (using WinBatch).

Since for our product most user edits will be straight text substitutions
(e.g. "Name" for "Description" or "File Name" for "Document Number"),  Word
macros will do the substitutions based on a correlation table stored as a
text file. This is a danger area, by the way, since you've got to make sure
that text substitutions don't mess up text within links or topic property
information; by supplying the macros, we (hope we) can control this.

Also, since we've got several Help projects, we're including a WinBatch
program that compiles the entire Help system and places the distributables
(HLPs, CNTs, DLLs, etc.) into a single directory that our customers can Zip
up for distribution.

This isn't a fool-proof solution of course; but we do believe it's a
workable compromise that gives customers the ability rework the Help system
for their needs, makes it straightforward for them to do so with their
existing resources, and does so without imposing an undue burden on us (no
serious hand-holding should be necessary). We'll see how it works out...

> One more ?, are the .hlp and .cnt extensions of WinHelp projects
universal,
> or are they RoboHelp specific?

HLP and CNT and PRJ are "universal" WinHelp extensions.

Hope this helps. If you have any specific questions, feel free to contact me
off-list.

/Steven Feldberg
Feldberg Communications
steven -at- icu -dot- com