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:Matching the CAPITALIZATION of the interface? From:Geoff Hart <ghart -at- videotron -dot- ca> To:"TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 18 Feb 2005 09:21:22 -0500
Steven Jong reports: <<We are documenting a product with hundreds of
named, permanent data objects that you can create and modify. The
interface includes complex, multi-tabbed forms for each class of
object, often with labeled sections on each tab. In the last major
release of the product, the company hired an outside consulting firm to
redesign the forms. The redesign included setting the form names and
section labels in uppercase.>>
Let's hear it for consultants, huh? The problem with this kind of
approach is that by the time we anglophones escape high school, we've
learned that capital letters serve a specific purpose in the English
language, and most of us get really good at understanding that purpose.
(For everyone else, there's MasterEditor.) For those of us who have
been grappling with computers for more than 20 years, we've also
learned that all menus and menu choices and icon labels and tooltips
and dialog box names everywhere use initial caps followed by lowercase.
Arbitrarily choosing a convention that contradicts everything we've
learned (in my case, over 40+ years) begs the question of what this
adds from the user's standpoint. It might be argued that something
entirely capitalized is clearly being used as a visual label rather
than a normal word in running text, and though that explanation has
some logic behind it, it ignores the larger context: we still
communicate how to use an interface by reading instructions written in
words, and we have not learned to use all-caps in any kind of efficient
way. Nor is there any advantage to doing so.
It might also be argued that capitalizing a command or menu or other
label avoids the necessity of having to use quotation marks (press the
"Button" button) or font formatting (press the _Button_ button) in our
documentation. This has a slightly more convincing ring to it, but
again fails the real-life test: fully capitalized terms are
demonstrably harder to read than words that follow normal use of case
(this is why all-caps headings have gone out of style), and when a text
is littered with them, the visual blobs created by capitalization draw
the eye, even when small caps are used to mitigate this effect.
All that to say, at considerable length: the consultants screwed up,
and their advice should be ignored in this specific case. Reality being
what it is, that's not going to happen until a manager with no stake in
this decision retires and someone less easily embarrassed takes over,
and at least until you can get the interface changed, you'll have to
live with it. To wit:
<<let's say there's an Access object named Write that you define and
modify using a form titled "ACCESS Write" (the form name is in
uppercase on screen) and on the front tab there's a section labeled
"PARAMETERS" (the section label is in uppercase on the form). My
question: In references to the forms or their sections, which of the
following is common practice?>>
Both your options (matching the capitalization in the interface versus
formatting the words the way you would do in running text) are common
practice. The more interesting question is which practice is more
effective for the reader, or at least which is less annoying.
<<(A) In the PARAMETERS section of the ACCESS form, select blah blah
blah...>>
This has the virtue of matching the interface, and in the past, I've
been a firm advocate of this approach when not carried to extremes.
Lately, for the reasons outlined above and others, I've come to
question whether this is truly necessary or useful.
<<(B) In the Parameters section of the Access form, select blah blah
blah...>>
In my own documentation projects, I've increasingly used this approach,
on the logic that (as you note) readers should quickly figure out that
the capitalization doesn't match. (I do, however, place keywords in
quotes to make them stand out from the surrounding function words. It's
a bit distracting, but less so than other alternatives that use
stronger formatting.) So long as the interface isn't case-sensitive
(e.g., so long as Access = ACCESS), the mismatch is irrelevant for most
practical purposes. In Unix, on the other hand, you couldn't get away
with the mismatch.
I've seen many recommendations in favor of one or the other option, but
suspect that most of these amount to debating the number of angels that
can dance on a pin-out diagram. I've yet to see any compelling study
that conclusively demonstrates the superiority of one over the others.
That being the case, repeat the techwhirler mantra: You can't solve a
bad interface with good documentation.
--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
www.geoff-hart.com
WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo: http://www.webworks.com/techwr-l
Doc-To-Help 7.5 Professional: New version with new features, improved performance and reliability, plus much more! Download your free trial today at www.componentone.com/techwrlfeb.
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.