RE: Providing fully customizable online Help? (Take II)

["Lorraine Butchart" <Lorraine -dot- Butchart -at- corel -dot- com>]

Geoff Hart wrote:

>Jim Shaeffer suggested that I "glossed over this phrase from the
original
>poster": <<complete with forms, dialog boxes, and menu
>commands that we would never have foreseen.>>

>True enough. I assumed that the original poster meant that the
developers know all existing 
>interface objects, but have no clear idea how they will be combined in
practice--rather than 
>assuming that the users could create interface objects nobody had ever
seen before. In 
>hindsight, not necessarily a good assumption, but if true, the task is
very similar to 
>documenting a programming language's API, and checking the archives for
information using 
>related keywords could provide additional insights.

>But as Jim suggests, if the software is more protean than I imagined,
this is a truly 
>intractable documentation problem.

And Jim Shaeffer wrote

>Of course, if the product in question is actually equivalent 
>to a development environment, then we've entered a whole 
>different arena of documentation.

My reply:

The product in question is not a development environment, but rather the
"developed environment" (an XML text editor) created by us and enhanced
by end-use customizers and developers using a development environment
that we provide. This development environment will come complete with a
large library of APIs, a nice graphical interface, and extensive
documentation for customizing the developed environment. We are planning
to produce this set of documentation as HTML help (.chm) files, or
possibly even in the new HTML Help version 2 format (.hxs) and make it
so that it integrates nicely with the Visual Studio .NET help files.
This is not my project. 

My project is to create a very basic help file for the developed
environment (the text editor) in a format that developers/customizers
can easily customize/edit/annotate/add to/subtract from. In addition to
help topics covering the basic editing functions that will be part of
every customization of this product, I can also provide some basic
fill-in-the-blank help topics for common editing functions such as find
and replace, spell-checking, and so on, that customizers could edit
according to how they implement the function in question. However, there
will invariably be some features of different customizations that we, as
the original product developers, would never have thought of, since many
of our customers will be using this product for highly specialized
purposes. For this reason, it's not enough to simply provide a set of
pre-determined topics from which developers can pick and choose. They
have to be able to create their own topics and add them to the basic
help file.

I've been getting some interesting ideas off-list from various list
members (thank you all), and am hoping to get a few more. Once we
examine our options and decide how we're going to deal with this, I'll
sum up the answers I've received for the list and let you know what we
decide on.

Or maybe Geoff is right, and it really is an "intractable documentation
problem". ;-)

\Lorraine (aka "the original poster")


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.