Re: Best Documentation

Subject: Re: Best Documentation
From: Martha J Davidson <editrix -at- slip -dot- net>
To: techwr-l -at- lists -dot- raycomm -dot- com
Date: Wed, 09 Feb 2000 10:10:53 -0800

OK, I can't restrain myself any longer. I'm going to
comment on this thread, because I've run across a
number of technical writing projects that resulted in
poor documentation because of the writer's writing
skill, and not because of planning, analysis, or any
other factor in the process.

At 04:07 PM 2/8/00 -0800, Tony Markatos wrote:
>P.S. Standardization of terminology is part of analysis.
>In fact, it is impossible to perform an effective task analysis
>without addressing standardization in a big way!

A comprehensive style guide does not guarantee a
well-written document. Standardizing terminology
is one important part of specifying style, but having
standardized terminology is not enough to ensure
that a writer will use those terms, and use them

And, even if the writer does use the standardized terminology,
there is nothing inherent in good task analysis to ensure that
these terms will appear in clearly formatted paragraphs, in
sentences that use good syntax, and in which the logic
flows clearly.

Unfortunately, there are, as in any profession,
technical writers who do not write well, or who do
not understand the technology they are documenting
well enough to express that understanding clearly
in their writing.

It happens. I have seen it. More times than I would care to
count. I have seen it in colleagues; I have seen it in writing
samples submitted to me as an interviewer; and I have seen
it in manuals for software I was attempting to learn and use.

Martha Jane {Kolman | Davidson}
Dances With Words
mailto:editrix -at- slip -dot- net

"If I am not for myself, who will be for me,
If I am only for myself, what am I,
If not now, when?"
--Hillel, Mishna, "Sayings of the Fathers," 1:13

Previous by Author: Re: Web Portfolios
Next by Author: Re: Knocking 'em dead at a new job
Previous by Thread: RE: Best Documentation
Next by Thread: Fw: Best Documentation

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

Sponsored Ads

Sponsored Ads