Writing question

Amy Speed speed at PARADIGMTECH.COM
Thu Nov 11 19:49:11 UTC 1999

Ouch, to the tech writers! As a technical writer myself, I often find it
frustrating that software developers don't know or care about proper
capitalization conventions. I worked for one software company that allowed
me to go to the developers with my corrections. The company for which I
currently work does not take suggestions from technical writers. And, of
course, once they do something wrong once, it has to remain incorrect for
consistency's sake. Frustrating, indeed. Especially when I am forced to use
their mistakes in my writing.

As a general rule, program titles (or dialog box titles) should be
capitalized as book titles ... all word capitalized except for prepositions
and conjunctions (but never with CAPS LOCK!). Field names are a gray area.
Microsoft capitalizes only the first letter of a word or phrase. Other
companies like to capitalize field names as they would program titles.
Whatever the company decides, the convention must be carried over into the
documentation. For all other text, I always follow the rules any dope can
learn in high school English.

In my experience, most technical writers are not actively involved in the
decisions of these conventions. Some may be poor editors. In any case, I
certainly agree with Andrea that software developers need to agree to a
standard (preferably Standard English rules) and stick with it. This is
necessary for a quality intuitive user interface (clarity, accuracy, etc.).
I would love to be more involved in presentation issues that involve words.
However, until programmers understand that tech writers' skills are just as
important as theirs, it probably won't happen.


P.S. Some tech writers are computer science graduates, rather than English
graduates. Without trying to step on anyone's toes, a company will usually
benefit more with an English expert than a computer expert as a tech writer.
Are the reasons as obvious to you as they are to me?

-----Original Message-----
From: A. Vine <avine at ENG.SUN.COM>
Date: Thursday, November 11, 1999 12:07 PM
Subject: Re: Writing question

>"James E. Clapp" wrote:
>> When words that are not normally capitalized are capitalized it slows me
>> because in reading my mind gives those words a little extra stress.
>> often they slow me down more because I get annoyed that I was duped into
>> giving special stress to words that really didn't need it, and annoyed
>> conventional capitalization rules readers rely upon [capitalization
>> proper noun] are being disregarded, and annoyed at the affectation [it's
>> Cosmo-style overuse of italics], and so on; but that's probably just me.)
>Not just you, I assure you.  One of the reasons I want to have some
research to
>back up my claim is that I want to get folks in the computer industry,
>the tech writers, to stop capitalizing a word just because it might be a
>computer term or command somewhere somehow.  Tech writing and user
>should not be special in this regard, and I believe the excess
>makes for an unfriendly interface.  It certainly bugs me.
>> I'm sure the caps are often thrown in not to give special emphasis but
>> because the writer has a vague feeling that important words, especially
>> are supposed to be capitalized.  I suspect that much capitalization of
>> sort is really quite unconscious.
>And born of ignorance.  English isn't German.  Heck, these days, German
>> Come to think of it, another thing that slows me down is writing with no
>> When i see writing in which words or names or abbreviations that would
>> conventionally be capitalized are not--which seldom occurs in the ads
>> find it quite distracting.  This obviously has nothing to do with the
>> features of the I-shape as distinguished from the i-shape: Much of what
>> text readable or not is just a question of whether the conventions that
>> are accustomed to from a lifetime of reading are followed.  Anything that
>> departs from the convention tends to cause a little hiccup.
>not an e.e.cummings fan, eh?
>> Of course, change can occur, and new conventions can replace old.  See,
>> the free and frequent capitalization in the Declaration of Independence
>> the capitalization of virtually all nouns in the Constitution of the
>> States.
>But Those Words were Important, Weren't They?
>(No kidding, that's the way many messages are capitalized when I get them.)

More information about the Ads-l mailing list