Re: An Engineer has infected my young mind!

Subject: Re: An Engineer has infected my young mind!
From: "Krezel, Lillian" <Lillian -dot- Krezel -at- midata-ebs -dot- com>
To: "'TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM'" <TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM>
Date: Thu, 18 May 2000 16:16:46 -0400

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

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,

Previous by Author: RE: Whose action was that, anyway?
Next by Author: RE: Need help with a term
Previous by Thread: RE: An Engineer has infected my young mind!
Next by Thread: Re: An Engineer has infected my young mind!

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

Sponsored Ads