Planning a Help Project

[Steve Owens <uso01 -at- EAGLE -dot- UNIDATA -dot- COM>]

> Our methodology is a combination of Information Mapping and Weiss's
> methods.  We separate information into modules based on information
> type. For example, a module might be a step-by-step procedure, or it
> might be an explanation of a concept. Usually, (but not necessarily) a
> module is from 1/2 to 1 page long.

        Interesting... could you post some references for this technique?
It sounds like it's worth reading up on...

> This modular writing, all developed in one tool, allows us to quickly
> build documents in different media. (e.g., all of the introductory
> modules might go in on-line help as well as a "Getting Started" paper
> guide).

        You don't say what tool you're using.  I'm curious about that.
I recently saw an extremely effusive recommendation for a product named
MAXTHINK, with a secondary reference to a product named TRANSTEXT, both
for MS-DOS Windows, I believe.

> OUR DEVELOPMENT STRATEGY
> [...keeping all of the modules in a Lotus Notes database...]

> One of the many disadvantages of this system is that any changes made
> to the RoboHelp/Word file must also be documented in the Lotus Notes
> database (if the database is to be of any use for maintenance and
> developing test plans).  So while the database gives us some essential
> information and gives us the ability to manipulate that information,
> it significantly increases the amount of work writers must do to
> document their writing decisions.

        It sounds as if you've got a weak link here in the document
editing process - are you saying writers have to do the editing and
testing using RoboHelp/Word, then start up Lotus Notes and document
the changes?  This means a major context shift and duplicated work
(writing down what you changed after you've already written the
changes).  Maybe you should look for some editing process that would
be more integrated with Lotus Notes?

> How do other people develop on-line help, especially people in large
> writing teams?

        I'm it for our company.  I essentially take all of the documents
created for the product and build online help files from there. We're
looking for other methods to do this, particularly to single-source our
online help and printed documents.  Bristol Technology's Hyperhelp is
one route we're considering.

> How do other people test their on-line help to make sure all of the
> hypertext links work and that pressing F1 in a particular field brings
> up the right help topic?

        Testing to make sure the links work... that *should* be handled
by the technology, when you compile the help files.  I'm not that
familiar with the MS-Windows help system, but I can't believe that there
isn't something to deal with this, among the many third-party products
for building MS-Windows help...

        Testing the context-sensitive aspect is trickier, although you
don't really give enough information on how you define it.  Again, I
would expect there to be a tool that examines all of the contexts and
checks the files to make sure there are no holes.  As to the "right"
help topic, that's a human judgement.  One thing you could do is define
the set of all contexts and subcontexts in your product, then establish
for each module which contexts or subcontexts should point to it.

        One thing I've done for menu applications in the past is map
out the menus graphically, using something akin to a flowchart.  A
product that helps with this kind of task is Visio, a
flowchart-oriented drawing program.  I found that the visual map was
a lot more useful in discussions of the product.

Steven J. Owens
uso01 -at- unidata -dot- com