RE: being too picky? (long)

Subject: RE: being too picky? (long)
From: "Rock, Megan" <Megan -dot- Rock -at- fanucrobotics -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 23 Jun 2000 12:30:11 -0400

John Locke sez:
> This deserves an Andrew-like response:
>
> KNOW THY PRODUCT!!!

I'd love to! Unfortunately, it doesn't work that way around here. Our
process requires us to depend on the SME for 80% of the doc and 99% of the
technical expertise. They give us a draft and we rewrite here and there as
needed to make it comply with our style guide. After a few rounds of this,
they do a final sign off on the technical accuracy and completeness of the
manual. Our editor signs off on grammatical accuracy and compliance with
our style guide.

I know it is hard to believe, but there are too many products, options, and
features for our writing staff to be experts in them all. We're not
assigned the same product to document for each new software release, so we
never become experts in any one tool, and we're usually documenting five or
six unrelated products or features at a time.

I'm not trying to make excuses for myself, just explaining why we're not
SMEs! ;)

> You're not being too picky here--just too lazy. In your first
> definition,
> MFDC is a control. In your second definition, MFDC is a
> method. Which is it?

The developer and I hashed it out and eventually decided that MFDC should be
defined as a method for controlling the current. But it is also a software
option and a hardware option. According to the developer, MEDAR's manuals
cover the details about the MFDC, so for our manual's purposes the MFDC is a
method for controlling current.

> Your job is to find out, through whatever resources you can
> bring to bear.
> Try to find out the answer yourself before bothering your
> SMEs--they'll
> appreciate and respect you more the more resources you bring
> to your task.

Final draft is due this afternoon, as soon as SME determines that he doesn't
have any additions to the manual. SME is my best resource at this
particular moment.

But I digress. My original question wasn't really asking for a definition
of MFDC. I was more interested in discussing the challenges of trying to
convey to a non-writer the intricacies of the English language and to help
them understand how one word can change the meaning completely.

I once ran across a topic in an online help system where either "affect" was
used and I was quite sure, based on the context, that the developer meant to
use "effect." But either word could have been correct and would have made
sense, depending on what he was trying to convey.

When I went to discuss this with him, I had a difficult time explaining to
him the differences between "affect" and "effect." He didn't know much
about parts of speech (verb vs. noun, etc.), and he couldn't figure out how
to explain the topic to me using different words so that I could get a
better understanding of the context. Eventually I did figure out what he
was trying to say, and I was able to select the correct word.

This is another situation where I thought to myself, "I'm probably the only
person who will read this and even be aware of the difference between the
two words." It felt like I was wasting ten minutes of the poor developer's
time haggling over something that none of the users would have thought twice
about had I failed to catch it and fix it.

Megan E. Rock
Technical Writer
Product Information
megan -dot- rock -at- fanucrobotics -dot- com

All views expressed are entirely my own and are not necessarily shared
by my friends, co-workers, or employer.





Previous by Author: RE: Piracy, education and the techie garage sale
Next by Author: RE: being too picky?
Previous by Thread: RE: being too picky? (long)
Next by Thread: RE: being too picky? (long)


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

Sponsored Ads


Sponsored Ads