Re. "irreverence and humor" in documentation

[Geoff Hart <geoff-h -at- MTL -dot- FERIC -dot- CA>]

     A few comments, in response to the need to indicate how long some
     process would take, liked the idea of "go get a cup of coffee" because
     it was funny, irreverent, and humanized the documentation. Hear, hear!
     (Hear here?) I've seen a few notable examples of this that worked
     quite well... notably the manual for a piece of software called _The
     Incredible Machine_. The idea is to build a Rube Goldberg sort of
     device using a variety of tool buttons so the device would then solve
     some physical problem (e.g., use a "ramps" tool to guide falling
     bowling balls into a collection device) and, appropriately enough, the
     instructions are in the form of a looseleaf notebook created by the
     proverbial mad scientists. Cute, and more importantly, unintimidating
     to the intended audience... thus, very effective.

     Bottom line? If the audience is likely to be intimidated, and
     comprises kids, gamers, or others who aren't impressed by formalisms,
     go for it! But a few cautionary notes:

     1. This won't work for all audiences... senior management and many
     other individuals must don their "humorless hats" when they sit down
     behind their spreadsheet, and they won't take you seriously if you
     trivialize your subject. If you mock yourself, many readers will
     wonder how good you (thus, your product) really is... and this can
     cost you lots of dollars in sales.

     2. Humor is very subjective. Make sure that (i) you test it on a few
     typical audience members to be sure there's no offence (ask your
     political correctness guru, and if s/he isn't worried, neither should
     you be) and, more importantly, (ii) test it to be sure that the
     meaning is as clear as you thought. If you communicate clearly despite
     the humor, well and good... if not, you've failed in your primary
     task, explaining something. Note that you will rarely be the best
     judge of your own humor. As an inveterate punster ("Warning:
     incorrigible punster... please don't incorrige"), I've often
     discovered that I'm too subtle for my own good. You are too... count
     on it.

     3. Like any other spice you use in your cooking, humor can be
     overused. Treat it like cayenne: a little dab'l'do'ya.

     --Geoff Hart   geoff-h -at- mtl -dot- feric -dot- ca
     #8^{)}