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.
>... when using the
>function name in descriptive text, I display it in the same font as the
>rest of the paragraph.
Do you separate it with quotes or anything? I have found this technique
to be woefully inadequate when functions names are common nouns or verbs.
Sentences become extremely difficult to read because the function name
is easily misread:
In this case, contours is used instead of gradients, because map
is completed.
Which would be much clearer as:
In this case, "contours" is used instead of "gradients", because
"map" is completed.
or
In this case, CONTOURS is used instead of GRADIENTS, because MAP
is completed.
Better still, to our way of thinking, a nonproportional font becomes a
symbol indicating that the term is part of the program's dialect ("language"
would be confusing here) and should not be treated as a regular part of the
English language.
Is there anyone out there who feels that common nouns and verbs should not
be used as program, function, or command names because of this potential
for confusion when describing the system? In defense of this convention, I
will argue that it is better to use such descriptive terms than arcane, made-
up ones, because it makes them easier for users to remember, which makes the
system seem friendlier, which in the long run, should make our jobs easier.
That's all folks!
-Matt Hicks
matt -at- unidata -dot- ucar -dot- edu
