RE: Best Documentation

[Kay Robart <kay -dot- robart -at- integratedconcepts -dot- com>]

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