RE: Click X, or click the X button?

["Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>]

McLauchlan, Kevin
 
> Other than the fact that it's not recommended in this-or-that style
guide,
> would anybody have trouble getting the meaning, or be confused if they
> encountered "Click [Next]" or "Press [Yes] on the PED keypad" in a
help
> page, with no 'Typographical conventions' page nearby to explain the
> mystery?

Well, Keith assured us that his audience includes "at least one guy who
needs to be reminded what a mouse click is." If he can be believed <g>,
that guy would be on the phone to the help desk complaining that he
couldn't understand your procedure (probably complaining about his
broken cup holder, too). 

But I have to wonder if Keith's solution isn't analogous to what's done
all too often in schools: dumbing down everything to accommodate the
slowest (or least engaged), and thus doing a disservice to the vast
majority. 

I guess we're back to "know your audience." And I'd argue that the vast,
vast majority of people who aren't computer neophytes will immediately
understand your square brackets, or any other consistent typographic
convention (e.g., bold) to identify interface elements. And they'll
appreciate having a 3-page procedure instead of a 10-page procedure. 

Chris D.'s rant is definitely a keeper, full of spot-on observations.
Including the cognitive load reference. 

Yes, I saw Leonard's contention that "research indicates" it's false.
Research indicates lots of things, many contradictory. How much and what
kind of research, using what kind of subjects with what kind of
background and familiarity with the subject matter? Etc., etc. 

I know from my personal experience, and from the experiences of a fair
number of (computer-literate) people in a variety of professions with
whom I've discussed this, that lots of repetitive "filler" verbiage and
unnecessary detail makes a document harder to read and use, and much
more frustrating. 

I'm absolutely certain that eliminating what isn't necessary or helpful
to the audience makes the document more useful and useable. The trick is
determining what is and isn't necessary, and balancing the trade-offs
when the audience includes people of widely different knowledge and
skills. 


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------








 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat