Re: An Engineer has infected my young mind!

["Sandy Harris" <sharris -at- dkl -dot- com>]

Andrew Plato wrote:

> > 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). ...
> 
> 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.

Right. If you only have time for one, I'd pick the reference stuff, if only
because you cannot easily write a tutorial without referring to it.

On the other hand, this does depend on audience. Most likely, customers will
need both a comprehensive reference and some tutorial material, but which is
more vital depends on the customers and product in complex ways.
 
> 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.

Lots of engineers are uninformed on those issues, too, of course.

> 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.

Yes.