Doc purpose and mutating Help topologies (was: RE: Minimalist? online help?)

[SIANNON -at- VISUS -dot- JNJ -dot- com]

The latest incarnation of content-vs.-style banter, found in the context of 
a Helpfile discussion, brings up another topic I'd like to hear 
opinions/anecdotes on:  the pros and cons of mutating doc types (usu. in 
electronic format).  I believe some of the recommendations about what to 
include/exclude from Helpfiles may be reversed, if the Helpfile is viewed 
as a medium, not a scope of use.

Philosophical context:
     The idea of a "standard" doc set is nice, but isn't always as standard 
as might be expected, esp. when the nature and limitations of the product 
factor in.
     For example, for physical (hardware) products, it is not always 
possible to assume access to a computer, so documentation is more often 
hardcopy.  For software applications, electronic formats can be more 
convenient, in the form of online Help, but "Help" differs by 
context/purpose: at-need help differs from reference material help differs 
from procedural (user) training. Companies developing software for internal 
use may rely on their internal support folks, and thus not include Help 
with their application. Companies with budget or PHB constraints may not 
believe it necessary to purchase user documentation ("who looks at it 
anyway?" says the one person not using the software), and may expect users 
to learn the app. from the helpfiles.  "Train the trainer" methodologies 
crop up more and more often, but often result in outdated documentation not 
getting updated when the app. is revised, and users not getting "retrained" 
on items that have changed.


So, at this point we find that the "standard" doc types may not meet our 
users' real needs. What do we do from there? Can we "casserole" some docs, 
without them turning into a gooey (or GUI) mess?

I believe so. However, I'd like to hear pro's and con's from other folks, 
since I am obviously biased.  What may seem easier maintenance to me in my 
current position might be a nightmare in another context, and I'd rather 
not be blindsided trying the same approach in a future contract just 
because I'm not experiencing snags now.


Ancedotal example of a working "casserole" doc:
     I am dealing with a complex, internally-developed-and-used system, 
containing multiple app.'s hooked into the same database, used by different 
groups of people at overlapping stages of occasionally-parallel physical 
processes.*  Each app. has no menu item or button with which to access help 
(developers' choice), and needless to say no context-sensitive help. 
Training is on-the-job, and half the users do not have individual 
workstations for storage of personal copies of paper manuals.
     I recently converted the training manuals we had developed (following 
the "standard" doc set) into WinHelp format CBTs that double as reference 
manuals, stored in a single central location accessible from any computer 
in the company (not all computers may have a browser installed, but all can 
read WinHelp files); from the Contents page, the user may choose one of 
four tutorials, or go to a reference page. Browse sequences walk through 
each step-by-step procedure within each process within each function set 
within the application.  Individual topics exist for each screen for more 
detailed reference, including variations within displayed contents that 
affect the procedures that may be used. To reduce screen clutter while 
still allowing detail, I put a screenshot of each screen or significant 
variation in it's own topic, to be called in a secondary window from either 
the tutorial topics or the reference topics, as needed. I used image maps 
on each screenshot to link pop-up descriptions or definitions to each 
control or major feature (user clicks on the feature, they see the 
detail--potentially pages of text description available from a single 
on-screen image without drowning the user in blocks of text they don't care 
to wade through, and don't need). I also included a glossary topic using 
pop-ups for each definition, so I can link those definitions as pop-ups to 
words within tutorial or reference topics if it seems appropriate. In a 
future step, I'll have it email a receipt when someone completes a 
tutorial, so "refresher" training can be quantified and verified.


I also heard from someone (on this list? I forget) who found traditional 
paper reference manuals were too fragile and cumbersome for certain active 
engineers, and so they made laminated quick-reference card keychains that 
could be hooked to a belt, and the users loved them.  I could see something 
like that used for business phone quick-reference, hooked to the handset 
cord so as not to be lost when the phone is moved or deskspace becomes a 
premium, as such references often are.


Shauna Iannone
----------------------
*(Recipe for CIM soup: take 1 or more sets of manufacturing hardware, 3 to 
5 different manual processes, and 5 dissimilar data systems on different 
platforms that you have no control over. Add 1 more database to collect 
never-before-collected data, several administrative, data collection, 
reporting and human interface applications, and then interface everything. 
Have engineers stir regularly, so it doesn't always stick. Apply heat and 
pressure until brain turns golden brown and crispy at the edges. Serve with 
lots of caffeine.)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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