Providing fully customizable online Help?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Lorraine Butchart is trying to create <<... a highly customizable content
editor... and part of what we want client developers/customizers to be able
to customize is the online Help. The editor and its core Help file as
shipped will be extremely basic, but customizers/developers will be able to
create an end-use editor as simple or as complex as required for their
situation or organization, complete with forms, dialog boxes, and menu
commands that we would never have foreseen.>>

If you have the luxury of being able to affect the software architecture,
this is easy to do: all you do is (for example) include a help button for
each interface object that the user can add to their homemade editor. So for
example, let's say they include the "clean up Word HTML" menu choice, the
act of adding that function would simultaneously add a button linked to the
help text for that function. An interesting variant on "embedded help"!

It might also be nice if you could create a database of help text, with each
chunk tied to its own interface object via a context ID; your programmers
could then compile the help file dynamically simply by extracting all
relevant chunks from the interface each time the user saves their new
configuration. A bit tricky to achieve, but providing the programmers are
willing to do this, not really rocket science. In fact, probably all they'd
have to do is create a list of project files, then feed those to the help
compiler.

These are all more complicated solutions than are really necessary. You
could succeed very simply by making sure that a context ID is associated
with each interface object so that clicking the Help button (or invoking
help in any other way) displays the correct help information. In short, if
you create a single context-sensitive help file that contains a topic for
every possible interface object, then there's no need to recompile the help
for each custom configuration.

The only real downside is that the user will also be able to find and read
help topics that aren't relevant to the configuration they've created. But
that's not a major problem. The more difficult thing to achieve if you adopt
this approach is remembering to write help topics that stand alone, because
you can't know in advance what other topics would link to them. But that
shouldn't be impossible, since most help files should be written this way
anyway.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FrameMaker-to-PDF TimeSavers Assistants let you enhance & automate navigation
in PDF doc sets (chapter tabs, next/prev chapter/pg, bookmarks, popup menus);
create interactive PDF forms, rollover popups; presentations: http://www.microtype.com

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.