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.
Subject:Re: How do I handle this one? From:"Bergen, Jane" <janeb -at- ANSWERSOFT -dot- COM> Date:Fri, 26 Sep 1997 13:33:35 -0500
From time to time, I've had to deal with the same kinds of problems---
especially with supervisors who are engineers when they review my
documents. Here are a few suggestions:
- Do you have previous Help projects or manuals? If so, you can use the
approach that you want to maintain consistency in voice and tone (thus
changing "the user" to "you") and terminology (changing "display" to
"appear" or using "select" versus "choose" and more).
- Do you have a good selection of reference books? I keep an arsenal of
style guides, dictionaries, desktop publishing books, grammar guides,
and other reference guides on my desk at all times. People might argue
with ME, but not with my reference books.
- Do you have good examples of writing from other manuals? I started a
"clip book" of photocopied pages from manuals (just selected pages, not
the entire manual!) that I thought were especially interesting or
well-written. It's very easy to casually leaf through some of these and
say softly, "Well, this is the kind of tone (or consistency, formatting,
conventions, structure, etc.) we're looking for....."
- Do you have a department style guide? If so, make sure it includes the
issues you mentioned. If not, start one. It may be a little late for
this case, but could sure help in the future.
It's going to be tough...there are no easy answers. Politics is an
important part of this, too. I'd use the word "we" about 99 percent more
often than "I" and other warm and fuzzy techniques.
Jane Bergen, Technical Writer,
AnswerSoft, Inc. Richardson, TX
janeb -at- answersoft -dot- com
On Friday, September 26, 1997 12:25 PM, Ron D Rhodes
[SMTP:Ron_D_Rhodes -at- MAIL -dot- BANKONE -dot- COM] wrote:
> Dear Writers,
> Here is my problem:
> I am collaborating with another author on a Help project. And,
> very adept at HDK, she doesn't have any formal training in
> tech-writing, editing, grammar, etc. We are supposed to agree
> some writing conventions and she has adopted some very unsound
> practices. The following are just a few examples.
> 1. No parallel structure.
> 2. An emotional attachment to the word "display" over "appear."
> red screen 'displays.'"
> 3. A condescending tone toward her audience. She uses "the user"
> instead of "you." "The user" can set the Autocorrect feature by
> clicking the Tools menu.
> My Question:
> I can let a lot of her habits go unchallenged. However, I need to
> some of her bad practices head on. But how? I am considered to
> equal in this project and, what's worse, her bosses are not
> professional writers either.
> Ron Rhodes
> ron_d_rhodes -at- mail -dot- bankone -dot- com
> In the first paragraph, I don't mean to imply that every
> needs formal training.