RE: Best Documentation

Subject: RE: Best Documentation
From: Kay Robart <kay -dot- robart -at- integratedconcepts -dot- com>
To: Anthony Markatos <tonymar -at- hotmail -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 9 Feb 2000 09:42:25 -0600

I'm sorry, Tony, I disagree. This is why we frequently do not
consider
subject matter experts like programmers and engineers capable of
writing
good documentation. They understand the subject thoroughly and can
perhaps even figure out how the information should be organized, but
many
do not have the writing skills to write comprehensibly to the
reader. They
are not taught to express themselves for any audience other than
other
subject matter experts, they cannot adapt the vocabulary if that is
needed,
and in some cases their sentences are overblown, convoluted, and
overly academic (or just plain illiterate). In fact, many readers
who
find documentation difficult to read just don't read it, leading to
hours
of wasted time trying to figure out how to make things work.

There is a rather famous incident where the release of VisiCalc, a
superior product in a market with few competitors at the time,
bombed
because of the poor documentation, which was called "abysmal" and
"turgid" by the reviewers. Later releases of products (Demo II and
Ventura
Publisher) written by the same person had state of the art
documentation
as a result. You can quibble that "abysmal" may refer to the content
and organization of the manual, and it does in part, but "turgid"
reflects
directly on the the writing ability.

Kay Robart

> Ginna Dowler said:
>
> ..We make electronic equipment for trains, and in one situation (before I
> started, of course), our maintenance instructions were poorly written and
> almost incomprehensible, even to us. The writer had poor grammar skills,
> used a number of different terms for the same thing, and was genenerally
> sloppy. The task analysis was fine, the drawings were fine. It was the
> actual text which was awful......
>
> Tony Markatos responds:
>
> Experience has made me a firm believer in the old saying: "Never sweat the
>
> details." Therefore, it is very difficult for me to envision a situation
> where analysis and planning were properly done, but the writer just
> totally
> botched the project with poor grammar.
>
>




Previous by Author: RE: Word numbering Question
Next by Author: RE: Level of writing
Previous by Thread: Re: Best Documentation
Next by Thread: RE: Re[2]: Best Documentation


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads