Re: being too picky? (long)

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

"Rock, Megan" wrote...
> 
> John Locke sez:
> > This deserves an Andrew-like response:
> > 
> > KNOW THY PRODUCT!!!

Right-on, baby. 

> 
> 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.

Then you're not a technical writer. Your company should change your title to
"word processor" or "editor."  

Just applying styles and obsessing over grammar is not what a tech writer does.
 Real writers know their products, technologies, and readers well enough to
make intelligent evaluations of the data SMEs hand to them. Real writers
educate their readers - not merely make things pretty enough to put in the box.

 
> 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.  

That does not mean you can't have some decent working knowledge of the
technologies your company produces. Your company makes robots for the auto
industry. It seems to me the onus is on you to get up to speed on robots and
welding tools so next time, you can make an intelligent decision about the
edits.

You control the docs, not the SME.  You should have the final say in what goes
and what doesn't. If you don't, well, then you're not a writer.  Writers have
control over the content. 

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

No, you're supposed to be a writer. And a real writer knows his/her topic as
well as he/she knows his/her audience. Nobody is asking you to become an
engineer. Merely that you should know your employer's products and technologies
well enough to make grammatical and English decisions about the documentation
intelligently. 

> 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.

Right, and thus you need to know what word is right. And the only way to make
that determination with any real accuracy is to both know English issues and
the technical issues and make a rational judgment based on your knowledge. If
all you have is just the English side of that equation, you cannot ever make a
rational judgment of which words work best. 

> 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.

As you should.  The discussion with this SME should have been about what
information he/she was trying to communicate, not what "affect" and "effect"
mean.  The meaning of those words is totally ancillary to the real issue: what
are is supposed to be communicated. 

Most of the engineers I know loathe tech writers who try to "explain" English
to them. I remember an engineer telling this writer once "My job isn't to worry
about the English. That's your job.  Do it and quit bothering me with this
grammar shit."  I was snickering under my breath. That engineer was a bit of a
dick, but he had a point.  It wasn't his responsibility to worry about the
English.  
 
Now, before any of you jump on me and tell me how important grammar is and how
the universe needs better grammar - I say: yes.  But good grammar slapped on
top of incorrect information is meaningless. It is like putting perfume on a
lump of crap. It is still crap.  If the substance is lacking, then it does not
matter whether you use good grammar or not. Crap is crap.  

Ideally, the substance is rock solid and the grammar is good. 

So the priority for any good documentation is: 

1. Content
2. Reader
3. Organization
4. Grammar/Good English

You can have 1, without 2 and 3. You can have 1 and 2 without 3. However, you
cannot have 4 without 1 and 2.  It is a cascading dependency.

Now, you can yell and scream and have 97 conniptions about this, but if you do
not understand the technologies you are documenting, I don't care how much you
obsess over English - you're not a writer. That's what editors do. 

Andrew Plato  

No, you cannot touch that. http://members.home.com/aplato 

__________________________________________________
Do You Yahoo!?
Get Yahoo! Mail - Free email you can access from anywhere!
http://mail.yahoo.com/