Matching the CAPITALIZATION of the interface?

[Geoff Hart <ghart -at- videotron -dot- ca>]

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.