RE: An Engineer has infected my young mind!

[Chuck Martin <CMartin -at- serena -dot- com>]

> -----Original Message-----
> From: Edwin Skau [mailto:eddy_skau -at- mailcity -dot- com]
> Sent: Thursday, May 18, 2000 10:13 PM
> Subject: Re: An Engineer has infected my young mind!
<snip>

> Coming to the point. 
> I would believe that the engineer has spent a lot more time 
> on the project than you have. 

This is more often than not the case because, even in the better shops, tech
writers are frequently brought in well after the planning and coding has
begun. However, this is not the best approach for producing quality
software.

If the application is 
> well-designed, that means, the user has been profiled well 
> and the application synergizes with their regular procedure 
> and work flow. 

This, OTOH, is a stretch, an extreme rarity. Most software--especially first
versions--is created by people who have a great idea, then hire (if they are
not already that) great coders to make the idea real. Most people who have
the ideas, and most people who write the code, are not interface and
interaction designers, and have not been trained as such. Nor is it likely
that the programmers have been out to talk to potential *real* users (who
often aren't the ones making the purchasing decisions) and find out what
their needs are, if the software would meet those needs, and how the
software can be designed to fit those needs.

The first release of a software application is 
> usually aimed at a market that will gobble up the product. 

First, instead of better, has caused the demise of many products (and
companies). This fallacy is thoroughly debunked in Alan Cooper's "The
Inmates are Running the Asylum."

> You may be surprised to learn that many of these users need a 
> whole lot less explaining than YOU did. 
> 
> A reference manual is usually what accompanies a first 
> release. 

Which is why so many people complain about documentation. Reference manuals,
especially with new software, do not aid users in completing their tasks and
do not make up for what is usually poor design.

Many managers and project leads, however, often direct that the
documentation must clean up after bad software.

Further tutorials and user guides should be based on 
> feedback 
> via an informative feedback form that goes with the reference 
> manual. If your information is based on actual user queries and 
> NOT ON YOUR PRESUMPTION, it will serve the end user better.

Once you start getting feedback from users, it is too late. The feedback
should have come from investigating users before the code (and the manuals)
was even written. 

Good documentation can be done right the first time, just as good software
can be done right the first time. Because so many of us are trained in
creating good, usable documentation and in learning about and understanding
real users, the documentation for version 1 of a product is often better
than the product itself.

> 
> The engineer is not your enemy. He is the one that creates a job 
> for you. Respect his opinion, ask him for reasons, evaluate them 
> and then give good reasons for not accepting them. If he has 
> an attitude problem, you are not going to make work easier by 
> wearing one of your own. And remember, no matter how good 
> your boss thinks you are, it is easier to let go of a writer 
> than an engineer.
> 

An engineer may not be my enemy, but he (or she) certainly can be to the end
user, the one that often times is forced to work with a badly designed
product. And programmers don't create jobs for technical writers; they just
create more jobs because so many technical writers have to clean up after
the shoddy work performed by programmers who think they are god's gift to
the software world. 

Technical writers are often the only ones advocating for the users. Others
may say that they are, but their deeds do not match their words. 

--
"I don't entirely understand it but it is true: Highly skilled carpenters
don't get insulted when told they are not architects, but highly skilled
programmers do get insulted when they are told they are not UI designers."
     - anonymous programmer quoted in "GUI Bloopers"
       by Jeff Johnson

Chuck Martin, Sr. Technical Writer
cmartin -at- serena -dot- com 


***********************************************************************
This email and any files transmitted with it are confidential and 
intended solely for the use of the individual or entity to whom they   
are addressed. Any unauthorized review, use, disclosure or distribution 
is prohibited. If you are not the intended recipient, please contact 
the sender by reply e-mail and destroy all copies of the original 
message. 
***********************************************************************