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: Click X, or click the X button? From:Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Fri, 23 Oct 2009 08:20:09 -0700 (PDT)
Definitely, "Click X". If the GUI is so bad it's not clear that you're talking about a button, then identify it as a button. Otherwise, just say "No" (to quote one of my favorite 44 first ladies).
Never click *on* something, unless it really is a special something. You can click *on* an animation of a doggie wagging his tail, or *on* the foo parameter as it's displayed in the hooptie diagram. You can even click *on* a field in a table, but "on" could easily be unnecessary in that case -- user discretion advised. Never click *on* a button, check box, tab, menu, etc.
<rant>
Other style issues... How do you talk about setting check boxes (options in some GUI style guides) and radio buttons? What could be worse than, "To activate the Foo feature, enable the Foo checkbox"? When I have the latitude, I like to "turn on" and "turn off" check boxes and radio buttons. Also, I don't say what type of control it is... So I would simply say, "Turn on Foo". Or better yet, a table or bulleted list of options (check boxes) describing what they do... No verbs necessary. (I can hear the task-orientationalists shifting in their chairs.)
Here's an actual quote from a job I inherited -- "Click the box to place a checkmark in it." This statement shows up for every check box in the GUI. Come on...
Look, the audience has grown considerably. My mother in law knows the
basics of GUIs and most typical software (the new Microsoft GUIs
notwithstanding -- arrrgh!!!!!!). Gone are the days when you have to
tell people to type the text into the foo text box. You can just say,
"specify foo" and *everybody* knows what you mean. Ok, maybe not
*everybody*, but if you're working for a special audience, then you use
special guidelines. On average, nobody needs instructions to use
dialog box controls.
This isn't about saving keystrokes, it's about reducing cognitive load for the reader. Needless syllables make it harder to find what you actually have to do. There are lots of other shibboleths we should worry about. For example, starting every heading with a gerund. What can be more useless than a TOC where every entry begins with the word "Configuring"? When I scan the TOC I take configuring for granted... I'm not looking for the verb, I'm looking for the noun... the WHAT of the configuring task. Of course, we're not allowed to call it task oriented if it doesn't start with a gerund. And there's another shibboleth... Task orientation. We need a new round of research (the task-oriented research is decades old) to evaluate whether conceptual information is still flatly ignored, whether task orientation achieves what we want, whether we can redefine the *level* of our task orientation, whether there are better ways to orient gestures at the
computer toward the work at hand.
It's horrible documentation that describes how to use the controls, but doesn't provide the context or meaning of the controls. I know how to pull a lever. Does the lever operate the transmission or the brakes? I don't need to know how to type in a text box. I need to know what the effect of my string will be, and what other strings must already be specified before this one will make sense. I need to tie the GUI and the processing machine to my real-world needs. I need to do it quickly and efficiently.
</rant>
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
