Re: An Engineer has infected my young mind!

["Steven Shepard" <steves -at- yardi -dot- com>]

Sierra Godfrey  writes:
>The engineer 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 i
>t is to know the necessary actions that must be performed
>to get it working and maitain it, and follow short steps to
>achieve them.

>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. Not all the information at once, which they
>won't know what to do with.

Well, here's my take on it. He has his job to do, you have yours. I say this
to remind you of that fact.  Of course, telling him that may not be the
wisest career move. I believe you are on the right track.

While some types of applications might be better suited to a reference
manual. Most aren't. There might be a need for a reference manual for this
application. But a user will use that as a last resort.

The user is trying to get a job done. They are interested in the task they
are trying to perform, not function the application forces on them. Stick to
your guns, your users will thank you for it. Start from the users
perspective and write from their point of view.

There are two groups that think the users want reference manuals...
engineers, who love reference manuals, and tech support people, who need
reference manuals. I have worked in tech support and while that experience
has been invaluable in tech writing, the tendency I brought form that
experience is to over document.