TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I'm sorry, Tony, I disagree. This is why we frequently do not
subject matter experts like programmers and engineers capable of
good documentation. They understand the subject thoroughly and can
perhaps even figure out how the information should be organized, but
do not have the writing skills to write comprehensibly to the
are not taught to express themselves for any audience other than
subject matter experts, they cannot adapt the vocabulary if that is
and in some cases their sentences are overblown, convoluted, and
overly academic (or just plain illiterate). In fact, many readers
find documentation difficult to read just don't read it, leading to
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,
because of the poor documentation, which was called "abysmal" and
"turgid" by the reviewers. Later releases of products (Demo II and
Publisher) written by the same person had state of the art
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"
directly on the the writing ability.
> 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
> botched the project with poor grammar.