Reference Data and Online Help

Subject: Reference Data and Online Help
From: Steven Oppenheimer <Steven -at- OppenheimerCommunications -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 22 Jun 2004 23:54:35 -0400


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.



Follow-Ups:

Previous by Author: How to set up a listserve?
Next by Author: Re: Context-sensitive vs. navigational help
Previous by Thread: Dangers of grammatical criticisms
Next by Thread: Re: Reference Data and Online Help


What this post helpful? Share it with friends and colleagues:


Sponsored Ads