Re: Workmanship (long)

[Mona Albano <mab -at- USER -dot- ROSE -dot- COM>]

I?d like to put in my 2 cents? worth. First, a recap:

Philip Sharman <sharman -at- WOWMEDIA -dot- COM> wrote:

>I would suggest that the first step to launch that change is for the users
>to write a strongly worded letter to the company saying that the
>documentation was unacceptable.
>
>If the company concerned never hears back from unhappy users, why should
>they change?


Melonie Holliman <LonieH -at- AOL -dot- COM> seconded the motion:

>IMHO, whenever I see poor technical writing it is my duty to my profession
>to notify the company from which it came. ?
>Too many times we have discussed how little we are valued. The only way
>a company will know better is by feedback. 
>? I encourage feedback from customers on my manuals in any way I can

>By the way, my company learned the hard way that a good writer is important.
>The last tech writer here did not meet the users needs. The users would not 
>even look at the manual; they would call technical support instead.


Bruce Brodersen <baruch -at- TELEPORT -dot- COM> objected:

>What unmitigated chutzpah! Who made you the arbiter of technical
>writing standards? Who assigned you your "duty" to contact companies
>and trash other writers' work? IMHO! In my humble opinion indeed!
>
>How would you like someone who you've never met before to contact your
>employer or your client and strongly criticize your work? How smug the
>rationalization, "they should know their writing needs improvement."
>
>?contact the company. "You can use my services. I can make
>this better for you." But to go out an destroy business relationships,
>to go out and intentionally make people feel bad to satisfy your sense
>of professional standing, -that will hardly raise the esteem of
>technical writers in the world.


I respect Bruce's desire not to harm a writer's career, but I 
tend to side with Melonie on this one. 

I would not denigrate the writers, but it can help to report 
that documentation is hard to understand?-especially in a 
constructive manner, e.g. "I?d understand this better if the 
sentences were shorter." or "?the diagrams were bigger" or 
"?there was an explanation of xxx before we had to use it"
or "?you included some examples." I do not think of that as blaming 
the writer or trashing their reputations. I would think of the 
possible impact of each word, and I would try to send directly  
to the writers through a feedback form, since one of the things 
we don't know is the state of their office politics. 

We truly have no idea of the conditions. It?s possible, even probable, 
that the original programmers were gone; the specs were a year out 
of date, imprecise, or absent; the implementers were on another 
continent &  wouldn?t answer questions; the manager told the writer 
not to bother the developers; the prototype didn?t work; the industry, 
gizmo, operating system, and documentation software were all new to 
the writer; and the developers only started anwering questions and 
taking the writer seriously about Thursday before the document was due. 
As writers, we've run into these barriers over and over. We know that 
the writer may have fought the jargon, the tiny type, the lack of 
diagrams, and the peculiar structure all the way. 

And that the writer, justifiably, asked management to intervene 
to get quality input; and said, "I might pull a rabbit out of the hat 
but it will be a mangy rabbit." And the management said, "Yes, but 
no one seems to notice." 

As writers, when someone says, "I wouldn?t line a birdcage with your
work," we need to say, "Thank you! Where do you run into trouble?" 
because their feedback is the surest way to improve and perhaps the 
only way to get a company to listen. A good writer wants honest 
feedback to take to management. (Don't forget to praise the good 
ones, too!}

The Manitoba chapter of the STC surveyed 300 companies and found that,
on the average, professional re-writing of documentation paid for itself 
twice over in the first year and that professional writing of documentation
for new systems could pay for itself 100 times over?mostly in support costs.

It is only anguished cries of readers and groans of an over-worked 
technical support department that will get us the resources we need 
to do a good job, consistently, despite the odds. 

Hope this helps,
        Mona in Toronto

P.S.  George Scithers, the editor of Isaac Asimov?s Science Fiction Magazine
in the 1970s, had this Golden Rule of Rejection: 
"We don?t reject writers; we reject pieces of paper with typing on them." 
He wanted writers to send another piece of paper with better writing?
one that he could accept. 

P.P.S. There doesn't seem to be a good replacement for "workmanlike,"
does there?

Arrgh, there's a cat mussing up my papers! Gotta run...
--------------------------------------------------
Mona Albano
Technical Writer & Editor       Voice 416 469-1384
Toronto, Ontario, Canada          Fax 416 469-1720