Re: [Re:] What's with the new docs?

[Greg Cento <greg -at- FOCUS-SYSTEMS -dot- ON -dot- CA>]

Marilynne Smith muses,

>More than once I have been tempted to rewrite a few pages of a software
>manual, send it back to the seller, and offer to re-do the job.  The reason
>I didn't is because these people are foolish enough to pay for poor work,
>they are probably also foolish enough to stand behind it.


Well, I did just that two and a half years ago. I was the Circulation
Manager for a small magazine and using a powerful yet woefully documented
database system. And when I say the documentation was woeful I mean it
really sucked. The section on reporting, for example, consisted of screen
shot of each of the report and a line that said, "This is the suchandsuch
report". Not a word on how the information was derived from the database,
how to customize the reports, or even how to generate these reports in the
first place.

So during a break at a workshop on circulation management, I walked up to
the president of this company, introduced myself, informed him that I had a
degree in Professional Writing (have to establish a little ethos ya know)
and then told him that his documentation sucked. He looked at me and said,
"I know. I wrote it!" He laughed and then offered me a job rewriting it.

This was going to be great. The documentation was already in three ring
binder format. My jod would be to rewrite sections of it and then
periodically send them out to the 150 or so users that had on-going service
contracts with us.

And so began my career as a Technical Writer. Unfortunately, this story has
a bitter-sweet ending. The sweet part is that this encounter launched my
career as a Technical Writer, and I currently work with a terrific bunch of
people in an atmosphere where my skills are highly valued. Who could ask
for any more? The bitter part has to do with the year I spent working for
this first company. It was painful. Try as hard as I could to explain the
documentation process (which I supported with articles they never read), I
was consistently left out of the "planning process" as it existed. Whenever
I tried to explain the importance of audience analysis, I was told "our
users are idiots. period." After just about ever call into tech support,
someone would go on a tirade about how stupid our users were. Basically,
just about everyone had contempt for their customers. You know, the
hard-working people who were paying our bills. It wasn't long, as user
advocate, that some of that contempt starting coming my way. So I left, and
their documentation is still woefully inadequate (except for the three
chapters I managed to rewrite while I was there, which, BTW, stickout like
a sore thumb).

Is there a moral to this story? Well, maybe not a moral, but I am inclined
to agree with Marilynne's statement that prompted this trip down memory
lane. Bad documentation doesn't just happen. It's supported by the
structure and culture of the organization that creates it. I learned that
one the hard way.

Greg Cento
greg -at- focus-systems -dot- on -dot- ca
Focus Automation Systems Inc.