Re: Click X, or click the X button?

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.

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.



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.

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!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:


Previous by Author: Re: Tools versus skill set
Next by Author: Re: Click X, or click the X button?
Previous by Thread: Re: Click X, or click the X button?
Next by Thread: Re: Click X, or click the X button?

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

Sponsored Ads