Re: Lousy vs. good writing, good vs. bad manuals

[Doug Nickerson <Doug_Nickerson -at- ONSETCOMP -dot- COM>]

Diane -dot- Gutierrez -at- WESTGROUP -dot- COM,Internet writes:
>The posting about manuals making sense in the original Japanese touched a
>nerve with me. Let's get away from boring, three-pound, uninformative
>manuals, and also from unhelpful, obscure and explanation-deficient
>pamphlets that leave too many questions unanswered (and gives help numbers
>that are disconnected or don't answer outside West Coast business hours).
>Let's have friendly, chatty, background-information-giving,
>differential-describing USER INFORMATION that is good for a relaxing read
>before tangling with the hardware.  The people who put out the "for
>dummies"
>books have a good thing going.  Minimalist stuff is fine, but nothing is
>wrong with engaging, helpful information as well.

Hi Diane,

I've been writing a review of a minimalist C++ book this week. I've been
thinking about the issue of how friendly and background-giving a technical
reference should be--as it relates to computer books. I agree with the
tenor of your post.

What's the  definition of chatty? We're all well aware that occasionally
computer books cross the borders from chatty to bombastic to annoying.
(Although, if a computer author has a favorite sports team or a favorite
micro-brewed beer, it's something I think I should know about.)

I know you're talking about writing user manuals, instructions, and other
forms beside books, but I have noticed that one person's chatty is another
person's bombast and one person's background information can be another's
irrelevancy.

I think many of the O'Reilly books are popular because they successfully
walk the thin line between informal stylistic mannerisms and providing
reliable information.

Doug Nickerson
Bourne, MA.
Programmer/author/person/professional
doug_nickerson -at- onsetcomp -dot- com

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=