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.
>I'm updating a programming guide and I'm having a hard time over a verb that
>keeps turning up. Maybe I can get a second opinion...
>
>The GET command returns the value of the variable as a string.
>
>What this command does is it goes to another part of the program, retrieves
>the value, and uses it in the current function. I replaced "returns" with
>"retrieves", but the reviewer didn't like it.
>
>I'd rather use "retrieves" because it shows how the program goes to a
>destination and returns with information. I don't like "returns" because
>only indicates the journey back.
>
>Is "returns" an industry standard (check out Dilbert today at
>www.dilbert.com for a related funny) in the programming world, or can I push
>for the more accurate verb?
"Returns", in the community that you're writing for, means something very
specific. It does not mean what you want to say. It means what needs to
be said, which is what the programmer wrote.
This sense of the word comes from mathematics. In mathematics, a
"function" is a type of mapping between sets. A function is a rule
relating elements taken from one or more sets to a single element from
another set. That single element is typically a number, and you can use it
in expressions just like any other variable or number. For example, f(2,
4) + f(8, 8) is simply the sum of the numbers that function f "returns",
given inputs of (2, 4) and (8, 8). Now you can see the original need for a
verb here. Without a verb, and not just a noun like "result", talking
about these numbers that functions, er, "return", would be quite a nuisance.
Now, in programs, different parts of a program are continually sending
information back and forth to each other. Subroutine A yields control of
the CPU in order for subroutine B to retrieve or calculate some
value--known as "calling" subroutine B. Subroutine B sends this value back
to subroutine A when subroutine B finishes. Is this starting to sound
familiar? "Returning" in programming is the act of one subroutine--also
sometimes called a "function"--giving a number or other value back to a
subroutine that called it.
The similarity is even stronger when you consider that typical programming
languages have notations copied somewhat from mathematics. In particular,
you can say things like GETN(stdin) + GETN(stdin) to mean, "call the GETN
subroutine twice, have it retrieve a number from stdin each time, and sum
those numbers."
I'm going very, very fast here, but I hope this at least gives you a
general idea, and maybe some questions to ask the programmers. There is a
whole network of concepts here, and if you aren't familiar with them, you
won't know what "returns" means to programmers. But in that network of
words and ideas, "returns" means something very specific, not to be
confused with "retrieves". And what it means is very difficult to explain
to someone who isn't familiar with that whole conceptual world.
I think this is a good example of just how much is involved in the
nearly-always-neglected-but-of-highest-importance part of technical
writing: learning the concepts and terminology of the audience. I spend a
long time doing this before criticizing the words they're using. (*Then* I
criticize.) I think a good rule is to always understand the rationale, or
you could say the etymology, of each new term: what is was extended or
varied from, how the concept relates to others in the field, and why people
found it helpful to invent or borrow a word to mean that. If you don't
know those things, you aren't yet in a position to criticize the usage.
I bring this up because this is such a common phenomenon: tech writer or
copy editor knows "the rules" but doesn't know the speech community; tech
writer or copy editor proceeds to impose "the rules" onto the text,
undermining its credibility in that community and making the document less
clear and less useful to its readers.
I'm not saying you're doing that, since, after all, you're asking rather
than imposing. However, it's a little out of the spirit of "specific
subject matter takes precedence over generalized rules" to be asking tech
writers and not subject-matter experts. The only reason that I knew the
answer was because I worked as a programmer for twelve years, not because
I'm a tech writer.
By the way, if you want a word that programmers write all the time but *is*
almost always better replaced by a more-precise word, it's "use".
