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