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.
Anonymous wondered: <<I'm in the midst of a (major) disagreement at my
place of employment. Since beginning my career as a Technical Writer,
I've had it pounded into me that we are to use the "you", eliminate
"it/he/she", keep it informal and to the point, and use present tense
WHENEVER possible. Make it simple and easy to follow.>>
You should be able to find any number of textbooks on technical
writing, and any number of user manuals from Adobe, Microsoft, etc. to
support your case.
<<We now have a new Japanese Project Leader who wishes me to create a
completely new, FORMAL format, eliminating you, sprinkling it/he
liberally, and generally, creating a document that (in my opinion only)
would be very difficult to read through, especially for our Target
Audience. (Administrative IT personnel)...>>
In user documentation, the most important criterion with respect to
pronouns is that the actor must always be clear. "You" is rarely
necessary in documentation if you use the imperative voice ("do x"
instead of "you should do x" or "you're so screwed now that you've done
X" <g>), so the project leader may actually have a good case to make
here if you're overusing "you". Similarly, there's nothing wrong with
"it" if you're using this correctly as a pronoun with a clear
referrant.
"He" is generally accepted as a bad choice unless you're specifically
referring to male subjects; the overwhelming modern trend in the West
is towards gender-neutral writing, and given that your Japanese project
leader may be new to this discourse community, it's worthwhile helping
them to understand that by adopting a gender-specific style, they would
be annoying many readers and embarrassing themself. Fear of public
embarrassment is a powerful motivating force in all cultures, but
particularly so in Chinese culture--and I'd guess Japanese culture too,
but don't quote me on that.
Project leaders are often very sympathetic to the "if it ain't broke,
don't fix it" approach. Without being confrontational*, ask the project
leader what problem they are trying to solve, ask them to produce
evidence (not opinion or personal preference) that this really is a
problem, and ask them to provide high-quality examples of the style
they're asking you to try. Sometimes you can adopt some of their style
choices (not all) and thereby reach a compromise in which both of you
"win": they see that you've given in to some of their demands, and are
more likely to accept some of your demands in return.
* "I'd like to work with you to find an approach that works for both of
us, but most importantly for the reader. Let's define the design
criteria here. We have the following situations we need to cover in the
writing [e.g., defining the actor]. What do you dislike about the
current approach? How would you fix it? How about the following
solution instead?"
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
