Matching the CAPITALIZATION of the interface?

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)


Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

Doc-To-Help 7.5 Professional: New version with new features, improved performance and reliability, plus much more! Download your free trial today at

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 for more resources and info.

Matching the CAPITALIZATION of the interface: From: Steven Jong

Previous by Author: Using digital camera for illustrations?
Next by Author: Technical writing in China?
Previous by Thread: Matching the CAPITALIZATION of the interface
Next by Thread: RE: Matching the CAPITALIZATION of the interface

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

Sponsored Ads