Help! Documenting green screens on the web?

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

Dan Roberts is <<... now doc'ing a large greenscreen application--and I'm
stumped. The application lacks any sort of hierarchy (although it does have
certain conceptual areas--trade entry, financing trades, clearance, etc),
you can
get from any screen to any other screen by use of a command field (so
there's not much in the way of progression of screens), information entered
on one screen can affect multiple other functions.>>

If there are no formal dependencies (e.g., you can't get to 3 until you've
done 1 and 2), then there are nonetheless informal dependencies or
hierarchies based on how people are likely to use the product. For example,
they almost certainly have to find or select something before they can begin
working on it, they can't enter data until they log in, and so on. A good
first step towards creating useful documentation would be to identify the
most common tasks and provide instructions on the best or most logical or
least annoying way to accomplish those tasks.

But it also sounds like this has much the same interface as an online
encyclopedia: each "article" (here, a green screen) can be reached simply by
typing its name, without passing through any other screens. That being the
case, you need to create a simple reference manual that has two main
components:
- a really good index: a series of task names plus several synonyms, with a
cross-reference to the page or hyperlink to the screen of the documentation
that describes that module of the application. In short, if I want to enter
data, and the module for this is called "Screen input", you'd need at least
two index entries: "Entering data--see _Screen input_", and "Inputting
data--see _Screen input_"
- an alphabetical (or similarly logical) list of the modules, each with its
accompanying documentation, and links to various dependencies (e.g., how
changes on screen A affect the results on screen B). Think of this just like
encyclopedia articles arranged alphabetically but with cross-references:
people find what they're interested in by looking (alphabetically) through
the list until they find the right name, then read the instructions and
check out any "see also" references.

If the relationships between modules or screens is truly complex (e.g.,
changes in any one screen can potentially affect each other screen), then
you need to create a master table of dependencies for each module: list the
fields or settings or buttons or whatever for that screen down the left
side, and on the right side, indicate what modules are affected by those
changes. With luck, each screen only affects one or two other screens, and
the resulting table will be relatively simple. If not, you've got a tough
job ahead of you.

<<Currently we create doc in PDF for delivery via the web, but I'm wanting
to push for some sort of interactive help medium.>>

PDF strikes me as fairly useless for such an unstructured application unless
you explicitly design the PDF to be full of hyperlinks that help the user
deal with the dependencies I've discussed above. Since it's a Web-based
application, I'd suspect (as a user) that a much better solution would
involve context-sensitive help: add a "click here for docs" button on each
screen.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Take XML and Tech Writing courses online!  Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off!  http://www.online-learning.com/index.html.
---
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.