Re: An Engineer has infected my young mind!

["Krezel, Lillian" <Lillian -dot- Krezel -at- midata-ebs -dot- com>]

Dear Sierra,

There are many software engineers who seem to share the attitude you
describe. I.e., "the
product is so complex, only the initiated priesthood (a/k/a the software
engineer) can understand
it. If the users are too dumb to understand my software universe, it is
their problem. Why help
them out?"

Here's what I've done in similar situations:

- "Thanks for your thoughts. I'll consider your idea."  Then write short,
user-friendly steps.
Put the complex stuff in an appendix.

- Write short, user-friendly steps in one volume entitled "User Guide".
Index this thoroughly. 
Put all the reference stuff  in another volume entitled "Reference Guide".
Package them as a
documentation set.

- Write instructions for one function both your way and the engineer's way.
Give these samples
to your software testers or possible beta customers, and tell them you need
their assessment.
This is "testing the documentation." Get their comments in writing or email.
Then, if the engineer
complains about your work to your boss or in public, you can show your boss
that you 
did consider the engineer's approach, but you still think yours is better
for the customer. And
you'll have evidence of why.

-If a manual in the engineer's style already exists, ask your customer/tech
support people to
point out places where lack of straightforward explanation caused a lot of
support calls. More
evidence.

You said it yourself, the engineer "knows the most about the product . . ."
He doesn't need a
manual. Your customers do.

Welcome to techwriting. This is how it looks from here.

Good luck,
Lili