Re: An Engineer has infected my young mind!

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

> I am a young, relatively inexperienced technical writer.Nevertheless, I have
>  a permanent job where I am the only tech writer in the company. My boss and 
> his boss, the president of the company, have both let me know they are 
> pleased with my work.

..snip...

> 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 it is to know the

> necessary actions that must be performed to get it working and maitain it, 
> and follow short steps to achieve them.

You're both wrong - and both right.

A good manual addresses multiple audiences simultaneously. Some people prefer
straight reference data to tutorials (myself being one of those people). I find
tutorials boring and a waste of time - but I respect the fact that some readers
do like this. 

You should do both. If you don't have time - then I'm on the engineer's side.
Raw data is ugly but more functional that pretty tutorials. Put the tutorials
in on the next version.

Also, assuming that an engineer is a prick just because he/she has a differing
opinion about documentation is unfair. I've watched many a tech writer blab
their unwanted and uninformed opinions about user interfaces and software
functionality to engineers.  Their are things engineers know that you don't
know.  Engineers have a different perspective and that is not always a bad
thing. Try to see things through their eyes. 


Andrew Plato

Savor the down-home creamy goodness: http://members.home.com/aplato




__________________________________________________
Do You Yahoo!?
Send instant messages & get email alerts with Yahoo! Messenger.
http://im.yahoo.com/