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.
Kelli Lewis documents <<...dialog boxes, windows, forms, etc., I list the
"elements" of the UI, and then I define functionality. For example, Name
field - enter your username. Quantity drop-down list box - select the
quantity of whoosits from the drop-down list... someone here ... wants me to
remove the terms "field," "drop-down list box," "radio button," etc. from
these sections of the document [because] they are "engineering terms and
they will scare the average user." He says that the terms do not benefit
the user in any way and are useless.>>
"Scare" is a strong term, and though it's undoubtedly true for some readers,
it's exaggerating the point for most others. What's important to me is that
if the reader isn't a programmer, terms such as "radio button" and "combo
box" are entirely meaningless, and the rule of simplicity suggests that if
the words aren't adding meaning, they're just adding clutter and should be
deleted. Even for relatively sophisticated readers, the terms may not mean
much; for example, I've come across such terms frequently enough that I
should know them, but I don't use them in my work and thus would have to
think hard about the difference between a radio button and that other
thingum that looks just like it. Besides, in this age of MP3, who uses
radios any more? <g>
More seriously, the actual issue you're facing is how to identify the
portion of the screen that you're referring to, not how a programmer would
describe it. In many of these cases, adding adjectives (which button? Oh,
the radio button) really doesn't accomplish this goal. Only if there were
two areas labeled "Name" would calling one a field and the other a combo box
have much meaning (and the meaning is that there's an interface problem, not
a nomenclature problem). If the label "Name" is sufficient by itself to
point readers to the right part of the screen, then there's no need to add
any additional labeling; if it isn't sufficient, then a labeled screenshot
with callout arrows to show what the description refers to is more likely to
be helpful.
"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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members. http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more http://www.SolutionsEvents.com or 800-448-4230
---
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.
