Re: Developers

Subject: Re: Developers
From: Jane Bergen <janeber -at- CYBERRAMP -dot- NET>
Date: Thu, 17 Dec 1998 20:32:49 -0600

Many of us are just thankful to have ANYBODY read our docs! The
reasons they do this micro-editing vary...some are passionate for
accuracy and the only way they can understand the text is to translate
it to "engineer-eese"; others simply have to feel they have valuable
and valued input. Depending on the developer, you can discuss the
edits with him or her, or you can simply say, "Thanks! I'm grateful
you took so much time with this and I'll be sure to consider each of
your "suggestions" carefully." That's usually enough. Everyone's face
is saved.

Now, and this next point is IMPORTANT, if you do decide to discuss the
changes with the reviewer, you had by-golly better know your stuff. Be
able to explain WHY we don't use passive voice, WHY some term is
considered jargon, WHY a certain construction is better than the one
he or she suggested. Too many writers just hear "Passive is ugly" and
blindly go through the document slashing with a red machete. If you
can defend your decisions with FACTS (programmers love facts, studies,
credible sources, etc.), rather than wimpy "because that's the way we
do it" statements, you'll find your reviewers are more receptive to
your changes. Go into the discussion armed to the teeth with
information, samples, sources, and so on. You'll then be viewed as a
professional who really knows her stuff.

Good luck,

Jane
Jane Bergen, Technical Writer
Dallas, Texas
janeber -at- cyberramp -dot- net


> -----Original Message-----
> From: Technical Writers List; for all Technical Communication issues
> [mailto:TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU]On Behalf Of Leona L.
> Magee-Dupree
> Sent: Thursday, December 17, 1998 10:04 AM
> To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject: Developers
>
>
> I gave a copy of instructions to a developer and the
> developer ignored the
> instructions and changed the sentences from active to passive. The
> developer tried to edit the documentation. What does a
> technical writer
> have to do to get feedback about the accuracy of a document
> and not "tid
> bits" of how to write from someone who does not know how to
> write? Why do
> developers do this? How should we react?

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: Re: a good manual
Next by Author: Re: Skipping page numbering
Previous by Thread: Re: Developers
Next by Thread: Developers


What this post helpful? Share it with friends and colleagues:


Sponsored Ads