Re: Humor in technical writing

Subject: Re: Humor in technical writing
From: Elizabeth Ross <beth -at- vcubed -dot- com>
To: <v2cdimld -at- us -dot- ibm -dot- com>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 02 Oct 2000 16:07:50 -0400

Interestingly enough, here's what Philip Greenspun himself has to say (from
the article referenced below):

As long as I'm setting down all of the things that I hate about computer
books, let me add cheerfulness. Any complex software system has
portions that are well-designed and do the job and portions with holes big
enough to fall through. There is some kind of conspiracy among
computer book authors to cover both kinds of subsystems in the same
uniformly cheerful tone. This masks important distinctions among
sections of a program and can be incredibly annoying.

Suppose that you are up all night tearing your hair out because something
has gone wrong with your RDBMS. You turn to your technical
bookshelf and thumb through all the dbadmin guides. Perhaps you do find some
useful information but you become enraged by the cheerful tone
of the book. You are in this mess because the RDBMS vendor skimped on the
design and implementation of a critical system component. This
skimping may well have been documented somewhere ("the difference between a
bug and a feature is documentation") but you didn't see the
relevant caveats before the skimping brought down your service. Partly this
is because tech books don't have sections like "design idiocies that
are likely to fuck you over." When you finally do find the relevant passage,
it is phrased as though the design shortcoming were perfectly
reasonable. How else would you want the system to work?

So you feel utterly alone. As far as you can tell from reading the vendor's
official documentation and the combined products of the computer
book industry, nobody else has ever had a problem with this RDBMS. You are
the stupidest, unluckiest, and most incompetent person ever to
walk the face of the Earth.

Why do editors push authors into writing this way? Because there is a belief
that computers are intimidating. They aren't friendly enough to the
users so we'll make tech books cloyingly friendly to compensate. IMHO, this
idea sucks.

--
Elizabeth Ross
Senior Technical Writer, V3 Semiconductor Corp.
beth -at- vcubed -dot- com http://www.vcubed.com
Cogito cogito ergo cogito sum.


> From: v2cdimld -at- us -dot- ibm -dot- com
> Reply-To: v2cdimld -at- us -dot- ibm -dot- com
> Date: Mon, 2 Oct 2000 08:42:08 -0500
> To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
> Subject: Re: Humor in technical writing
>
>
> A description of a book (admittedly one I haven't read) that seems to use
> humour in the vein described by Sandy Harris can be found at:
> http://philip.greenspun.com/wtr/dead-trees/story.html . I found his humour
> enormously engaging, and his lessons in the publishing industry a pretty
> good reason *not* to get published...
>
> Marie Davis





Previous by Author: Re: Publish or Upload- correct use of terminology?
Next by Author: On-line tech writing class
Previous by Thread: Re: Humor in technical writing
Next by Thread: Re: Humor in technical writing


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


Sponsored Ads