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.
joe wrote:
<Tom, I quite agree that asking developers is a good place to go. In my
case, the developers are on one coast & I'm on the other.>
This is what e-mail is for! :-) I used to document stuff where half the
subject matter experts were in the South of France and I was in Reading. (Of
course, sometimes you don't get a good ANSWER from your SMEs unless you're
there in person. When that happens, phone calls often help. At least you
speak the same language. Well, almost. <g>)
<Interesting....one of the probs of asking developers is they might say, "I
know what it means when 'wrapper' is a verb" or "When I said, "The
developer can OR the logic,' that's what I meant--OR the logic!!!"
Sometimes the language one person or a subgroup uses works only within that
subgroup...and doesn't extend to a wider audience.>
Well, this is your judgement call. I once had a manager who had not heard
the phrase "radio buttons" to mean the multi-choice single-option selection
boxes. Because she had never heard the phrase before, she was convinced it
was a piece of abstruse jargon that NO ONE but a few online help geeks would
understand. She laid down a managerial decision: find some acceptable way to
describe a column or row of multiple options where you can only choose *one*
option, because "radio buttons" is jargon. She was right - and she was
wrong. She was right in that it's jargon. She was wrong in that it's a
short, simple phrase describing a specific type of multi-choice option that
was already in wide use: there was no reason why we SHOULDN'T have used it,
providing that we supplied a glossary for first-time users converting to
Windows from VAX who found it unrecognisable.
When a developer uses a word or a phrase in a way I find doesn't mesh with
standard English, I always check it out to find out if it's (a) singular to
that developer (b) unique to this company/department/team (c) standard
jargon within the group towards which this technical documentation is aimed.
If (a) I'll probably change it. If (c) I probably won't change it. If (b) I
may or may not change it - depends whether there's a standard option already
available that is in my judgement more familiar to the expected audience.
Language is communication. Language changes. The job of a technical writer
is to ensure that if jargon is used, it is jargon that communicates the idea
required to the intended audience: nothing more, nothing less.
That being said, I would probably edit this particular sentence to read:
This Java component is the wrapper for the second component, which is a C
program.
because like you, I don't like "wrappers" as a verb, and the Java
documentation agrees. But if the Java documentation changed, and I were
still writing documentation for Java developers, I would ignore my dislike
of "wrappers" as a verb and use it in order to communicate what was intended
in a way that would be understood by the intended audience.
My tuppence ha'penny this Monday.
Jane Carnall
"They are prisoners of their own dreams and illusions, as we were 30 years
ago. If the issue is between our and their illusions, we will never resolve
the conflict."
Unless stated otherwise, these opinions are mine, and mine alone. Apologies
for the long additional sig: it is added automatically and outwith my
control.
Home: hj -dot- carnall -at- virgin -dot- net
E-mail is an informal method of communication and may be subject to data corruption, interception and unauthorised amendment for which Digital Bridges Ltd will accept no liability. Therefore, it will normally be inappropriate to rely on information contained on e-mail without obtaining written confirmation.
This e-mail may contain confidential and/or privileged information. If you are not the intended recipient (or have received this e-mail in error) please notify the sender immediately and destroy this e-mail. Any unauthorized copying, disclosure or distribution of the material in this e-mail is strictly forbidden.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more at http://www.ehelp.com/techwr-l
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
