Re: Rhetoric And Technical Writing?

Subject: Re: Rhetoric And Technical Writing?
From: Janice Gelb <janice -dot- gelb -at- sun -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Wed, 22 Mar 2006 13:57:51 -0800

David Loveless wrote:

And I would like to make one thing clear... I never said that the
manual was the absolute end-all of technical documentation. I would
never be so foolish as to claim something that is entirely
unsupportable. However, I *did* say that my reviewers *chose* to read
above and beyond what they had to read because it was open,
refreshing, inviting, and pleasant. I mentioned that as an opener to
*my* belief that the field of technical writing in general needs to
change the style and design of our documents to become more user
friendly and as an attempt to tie that in to the current topic of

I want to emphasize that I do not disagree that a
lot of technical documentation could benefit from
a style more devoid of jargon and unnecessary
technical density. At the same time, the fact
that reviewers chose to read more of your book
frankly does not necessarily say anything about
whether it serves its purpose. I read novels for
enjoyment and admiration of writing style. I read
documentation to find out how to use a product.
The quicker I can find that information, and the
more understandable it is, the better the technical
documentation. I'm not saying your document doesn't
provide appropriate information. I'm just saying
that in general I don't want to have to read paragraphs
of friendly, inviting prose to get to the information
that will enable me to use the product.

I'm an editor and I've seen many cases where writers
write perfectly understandable sections of documentation
that provided interesting background information but
were pointless for the audience of their product.
Often when I ask them what *they* do when they buy
software, they see my point: very few of us sit down
and read a software manual cover to cover, and we're
technical documenters! Most of us buy the product,
maybe look at how to install it, then try to use
it. When we get stuck or want to do something tricky,
we consult the documentation.

Most technical documents are called something like
"Using Zooble" and not "The Joys of Zooble" for a

-- Janice

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


RE: Rhetoric And Technical Writing?: From: mlist
Re: Rhetoric And Technical Writing?: From: David Loveless

Previous by Author: Re: Boring documentation?
Next by Author: Re: Terminology question
Previous by Thread: Re: Rhetoric And Technical Writing?
Next by Thread: Re: Rhetoric And Technical Writing?

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

Sponsored Ads