RE. An Engineer has infected my young mind!

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Sierra Godfrey (though "kittenbreath" is a much more interesting name <g>)
has an engineer who <<... insists the manual should be presented as a
reference manual, with all the information there, and very little
tutorial-style steps. I disagree--the product is complex and difficult to
understand. I feel the only way a customer will be able to wade through it
is to know the necessary actions that must be performed to get it working
and maitain it...>>

The engineer's attitude always pushes my "you're an engineer, not a writer,
so stick with your own job" button, but giving in to the impulse and
actually saying that is counterproductive. If you're certain that you
understand the audience better than the engineer, then you need to convince
your managers (and perhaps even the engineer) that you're right. That means
getting access to the audience, either directly (on-site visits, phone
calls) or indirectly (what complaints is the technical support department
getting about the docs?)--but you'll need access to the audience, not simply
refer to "published studies", to make your point.

<<The engineer feels manuals should be read two to three times over, because
the information is densse, and include all points. I disagree. There are
different types of readers, to be sure, but my readers will not know
anything about this product and will need a lifeboat--user-friendly, short
steps.>>

That fits with my preconceptions, but again, you'll have to be sure that you
know your audience. If they're all clones of your engineer, then we're both
wrong. But the situation is rarely so "I win, he loses" as you may think.
Create the reference document the engineer is proposing, since that will
undoubtedly be useful to the users, but create an additional overview,
getting started, or tutorial document that shows people how to use the
product and how to make use of the reference manual. The engineer is
unlikely to object to you _adding_ material, but you'll have a fight on your
hands if you try to completely overrule him.

<<The engineer has crazy ideas about documentation, and indeed will not let
me have on my own, but first presents me with his version of the manual.>>

The question then becomes: who is responsible for delivering the manual? If
it's you, thank him for providing you with a detailed source document,
firmly point out that it's your job to produce the manual, and then use what
he's provided to write your own manual. You'll have a battle on your hands
convincing him to review only the content you produce, not how you've
presented that content, but stand up to him. The bad reputation of male
engineers has been earned honestly (speaking as one who works with engineers
daily and studied with them in a parallel program), but one thing I've
noticed is that most of them respect strength and conviction from someone
who can back their assertions with logic and hard facts. Get those hard
facts, present your case logically and convincingly, and don't back down for
an instant unless you know you're wrong and the engineer is right. And don't
forget to acknowledge when the engineer is correct, and incorporate that in
your final product.

<<How do you all deal with what engineers want and what you know should be
the correct way to present the info?>>

I out-argue them, which annoys them greatly, and particularly so when they
end up acknowledging that I've run rings around them logically and accept my
point. But in addition to that:

<<How do you incorporate what the engineer, who knows the most about the
product, is trying to say>>

By incorporating what the engineer, who knows the most about the product, is
trying to say. <g> But there's nothing to say that you must use his precise
words or approach. Take the facts, and present them effectively. Where
possible, preserve the guy's words and approach so that he feels you're
accepting some of what he says, but don't let the need to respect his
feelings inevitably get in the way of effective documentation. In short, you
can often steer a middle ground that involves picking the most important
battles to win, and conceding a few victories to the engineer now and then.
 
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer