Re: Funny technical writing--risky?

[Kevin McLauchlan <kmclauchlan -at- chrysalis-its -dot- com>]

On Friday 20 September 2002 11:16, Hart, Geoff wrote:
[...]
> There are risks to using humor, including:
> - Giving offense: What people consider funny is intensely
> subjective, and something that has your entire
> development staff rolling on the floor may have your
> product's users calling their lawyers. 

In that respect, there's the risk of giving actual offense, 
and the -- these days, more likely --  risk of giving an 
opportunity to take offense, to the burgeoning ranks of 
the professionally offended (i.e., those who make a point 
of looking for things to which they can take offense).

> Even if the joke
> might be funny under normal circumstances, the highly
> stressed user trying to print a memo with an angry boss
> looking over their shoulder and the user who just deleted
> a crucial file and needs to recover it may be less than
> receptive to your attempts to make them laugh.

With the Timex Helix instructions as the example, I 
don't think the humor was sufficiently involved or 
voluminous as to constitute a problem. It was a thread 
winding through the text, certainly, but it wasn't something 
that went on for pages (like that Charlie the Rooster joke). 
It was a word here-and-there, a phrase, or an introductory 
sentence on each page. The layout made it obvious what 
was the meat of each instruction.  I think that can easily 
be duplicated by a competent writer.

Also, when you are highly stressed, you often have 
trouble absorbing the very information that will help 
you. If a touch of humor -- NOT at your expense -- can 
break the cycle of mounting tension, then you may 
actually be able to proceed more efficiently once you've 
emitted a snicker or a chortle.

I'll warrant that you don't want the bomb-disposal people 
breaking into guffaws while the pliers are touching the 
wires... (it only hurts when I laugh).

> - Failing to communicate: Ever failed to understand a
> joke? Every told a joke that one of your friends didn't
> understand? The "language" and "grammar" of humor are far
> less well defined than their technical communication
> counterparts, and anyone who's been on this list for more
> than a week sees how even we, as a group, sometimes fail
> to understand each other. (And how we sometimes lack
> anything resembling a sense of humor. <g>) 

Well then. Fair warning. If you don't have any indication, 
other than your own ego, that you are even capable of 
writing in humorous fashion, it might be best to practice 
in a relatively non-employment-threatening venue like... 
oh... this group, perhaps.   If the average response 
consists of lots of question-marks, then, blah, blah, 
day job.  Ditto, if all the "appreciative" responses consist 
of groans.

> - Doing it
> badly: There are few things more uncomfortable than a
> joke that falls flat. Even if you don't offend anyone,
> and the reader easily understands your meaning, do you
> really want to be seen as a "lame" writer? ("Yeah, that
> was funny... back when I was in grade school.") 

Always a danger, but at least if it falls flat the silence 
is not as deafening as it would be in front of a comedy-club 
audience.  When you read failed humor, there's always 
the chance (given an ego of less than supernatural 
dimensions) that in the back of your mind you'll entertain 
at least the possibility that the fault lies with you.
When you are part of an audience in a club or other 
public venue, the reaction of other people tends to 
re-inforce your confidence that you are correct about 
the bozo on stage.  The moral, then, would be to avoid 
writing humorously (you hope) in technical documents that 
are intended to be read out loud to groups.

> - Distracting the reader: Success also has its perils. If
> the reader enjoys the joke, you're taking them out of the
> moment enough that they'll probably lose sight of what
> they're doing. When that happens, they're probably going
> to be annoyed at having to backtrack to rediscover their
> purpose or where they were in a series of steps.

Again, you might want to consider that bomb-defusing 
scenario. If your instructions are not only intricate but 
time-sensitive and flirting with physical danger, then I'd 
go easy on the humor. Otherwise, if you think your 
audience (at least, most of them) would be receptive, 
then go for it. What I liked about the Helix instructions 
was that all of the humor was brief, incidental, over in 
one sentence.  I agree that humor would be out of place 
if it needed a big build-up and lengthy paragraphs or 
pages to achieve each grin.

> Given these problems, humor is a technique best avoided
> if it doesn't accomplish something you can't accomplish
> in any other way. If badly done, the humor may fail to
> communicate, and after all, isn't that our primary goal?
> That's not to say you should never use humor, but before
> trying to do so, be very aware of the risks and take
> measures to reduce or eliminate them.

Well, I'd guess that many/all of the reasons you might 
choose to use humor in a technical document would be 
marketing reasons. You'd want to affect/modify the 
way people reacted to the product and the company, 
in addition to giving them the information that they 
needed  to make the product work as advertised.

I'd love to use a bit of humor in my own product 
documents, but the people in charge are convinced 
that a little company like ours, selling exclusively to 
big companies and governments, needs to appear 
stuffy ... er... conservative.

Apparently, security and crypto is no laughing matter, 
unless you get it wrong, and then it becomes a matter 
of "might as well laugh as cry".

/kevin    


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FrameMaker-to-PDF TimeSavers Assistants let you enhance & automate navigation
in PDF doc sets (chapter tabs, next/prev chapter/pg, bookmarks, popup menus);
create interactive PDF forms, rollover popups; presentations: http://www.microtype.com

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.