Reference Data and Online Help

[Steven Oppenheimer <Steven -at- OppenheimerCommunications -dot- com>]

Hey, all, help me out here.  First, some quick background by way of a 
story.  Four or five years ago I was on contract with a company that makes 
electronic equipment.  They had a piece of technology, an electronic 
black-box, where set up was done through a PC-based software program.  To 
set up this black box, there were many, many technical parameters that had 
to be fed into the black box, and these had to be entered in through the 
software.

I was asked to design the online help system to go with the PC 
software.  Important point:  The *only* documentation to be provided with 
this system was the online help.  No printed manual at all.  So... 
obviously, the various technical parameters had to be documented in the 
online help, if at all.

Only, the documentation manager refused to let me put any description of 
these technical parameters into the online help system.  His position 
was:  Online help should not have reference material, only procedural 
material.  So, I could document how to navigate the software, but could not 
explain the use or meanings of the dozens and dozens of data entry fields.

This was absurd, the reference material was essential for any user of the 
product.  A small holy war broke out between the documentation staff and 
the marketing manager for the product, and in the end the reference 
material was, in fact, included.

But, getting to my question -- I was so busy, trying to explain to the 
documentation manager why it was essential to include the descriptions of 
the technical parameters, it never occurred to me to ask him:  Just where 
does it say, only procedural material can go into online help, but never 
reference material?

So, I failed to ask the manager, but I can ask all of you now:  Does anyone 
know of some study, or textbook, or something that passes for a source of 
authority in the field of technical documentation, which states that online 
help should only have procedural material, but not reference material?  I'd 
sure like to know how that manager might have become so fixated on that 
idea.  Any leads or hints would be appreciated.

Steven Oppenheimer, M.A.
Oppenheimer Communications
Technical and Business Writing:  From Complexity To Clarity (SM)
Steven -at- OpComm -dot- com   www.OpComm.com   (301) 468-9233 


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

SEE THE ALL NEW ROBOHELP X5 IN ACTION: RoboHelp X5 is a giant leap forward
in Help authoring technology, featuring Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! http://www.macromedia.com/go/techwrldemo 

COMPONENTONE DOC-TO-HELP 7 PROFESSIONAL:  From a single set of Word documents, create online Help and printed documentation.  New version offers yearly subscription service, Natural Search, Modular TOC Utility, Image Map Editor, Theme Designer, Context String Editor, plus more. http://www.componentone.com/doctohelp .

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.