TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: To Dialog or Not To Dialog (#117530) From:Bill Burns <wburns -at- MICRON -dot- COM> Date:Mon, 1 Apr 1996 16:23:25 -0700
1-APR-1996 16:33:54.21
>cpmiller -at- cdesigns -dot- com (Charles Miller) wrote:
>>I'm currently writing a help system for a client and we seem to
>>have reached a semi-impasse on the use of a term. Throughout the
>>help file, I use the word "dialog," as in: 'The XYZ dialog allows
>>you to...' or 'To do dis 'n dat, you must use the XYZ dialog.'
>>The client is strenuously objecting to the use of the word "dialog"
>>because he says the users don't understand it. Although I pride
>>myself on a career of writing for the 'technically challenged,' I think
>>there *has to be *some minimal level of shared "technical" vocabulary
>>if we're to explain the operation of a hardware or software component.
><snip>
>I agree with you, Charles. There is a certain minimum vocabulary of
>concepts that users must have. A dialog (or better, IMO, "dialog
>box") is a standard concept these days.
>Yours Truly,
>John Hedtke
>Distinguished Member, STC
It's one thing to provide your users with enough information to make sense
out of your directions. It's another thing entirely to assume your users have
the knowledge of convention. Instead of simply using the standard terms and
assuming the user will understand their meaning, perhaps you should provide an
overview section with a list of key concepts and definitions. Obviously, if
you're writing for users with a software background, you won't need to provide
this information. However, if you're targeting the current market of home PC
users, you need to provide information for both the serialistic and the holistic
learner.
What type of audience is this documentation addressing? Unless the audience
itself merits extremely simplified language, a list of terms should be
sufficient to help out the user.
BTW, this issue is covered in Conrad Gottfredson's one-stop documentation
seminar.
Bill Burns
Assembly Training and Documentation Supervisor
WBURNS -at- MICRON -dot- COM
