Writing question

[Tom Kysilko]

Andrea Vine wrote (eliciting a good number of dittos):
>"James E. Clapp" wrote:
>>... and annoyed that
>> conventional capitalization rules readers rely upon [capitalization
signifies
>> proper noun] are being disregarded
>
>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,
including
>the tech writers, to stop capitalizing a word just because it might be a
>computer term or command somewhere somehow.

Background for the uninitiated:  The rules of a programming language
typically specify a list of reserved words.  These are words programmers
should use only as specified in that language.  These words can be, for
example, commands, parts of commands, function names, or variable names
that the software that processes code written in that language will always
treat the same way.  Programmers who use reserved words for other purposes
do so at the risk of getting unwelcome or unexpected results.  It is very
common for programmers to CAPITALIZE reserved words as they occur in the
code they write.  You don't have to understand the following the see the
point:

        IF USED(cUseAlias)
                LOCAL nOldSelect
                nOldSelect = SELECT()
                SELECT (cUseAlias)
        ELSE
                RETURN ""
        ENDIF

The mixed-case words are defined by the programmer, the capitalized words
are defined by rules of the language.  Writing code this way aids other
programmers in making sense of the code, and aids the original programmer
in finding errors.

Now when it comes to writing discursive prose for an audience of
programmers on topics in programming in a particular language, it seems
unnecessarily fussy to complain about writers who observe the orthographic
conventions of that language, when snatches of code or even individual
terms are tucked into the discursive part of the writing.  When so many
ordinary English words double as reserved words, it seems only natural to
give your readers a clue as to when you are using a reserved word.  To be
sure, context will usually decide it, but not always.   So following the
programming language conventions is the safest course.  I can see no
advantage in substituting a sentence more in accord with standard English
capitalization for something like:

"You need to do some additional checking following the DO WHILE loop if you
want to limit the search to the structural index."
or
"When you SET EXACT to ON, things change."
or
"The code in each function could be run by SETting [sic] PROCEDURE TO
viewscript.prg and calling the appropriate function."

All this said, if Andrea's research ever gets done, and if it demonstrates
that special marking of reserved words used within discursive prose adds no
clarity, but only ugliness, I will change my tune.  But I'd bet against it.

And none of this is to deny that software manuals are, with very few
exceptions, so horribly written as to be of very little help.  But their
defects in mechanics (as my old Warriner's calls it) are not the problem.

[All examples from the December 1999 issue of FoxPro Advisor]


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Tom Kysilko        Practical Data Services
  pds at visi.com       Saint Paul MN USA
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~