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: 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
