Re: Checking the checkers through inaccurate information

[Michael Priestley <mpriestley -at- VNET -dot- IBM -dot- COM>]

Carl Millholland writes:

>This sounds all too familiar.  From time to time I put
>a little documentation joke in my draft intended for
>a technical review.

and Will Kelly replies:

>Your little "documentation jokes" are wasting somebody's time. That person
>often times is somebody who has probably put in a full 8 hour day and still
>has to read your document. As a technical reviewer, I have encountered such
>"documentation jokes". Upon each encounter, the "joke" lowered the writer's
>credibility in my eyes as a professional and a team player. I made sure
>that I noted such jokes and that my client or manager was made aware.

Some people enjoy having their time wasted.  It's called having a sense
of humour.  It's definitely not something to try with reviewers you don't
know, or with final drafts, or with reviewers like you, but otherwise it
can work quite well.

I've tried this technique with good success on at least one project.  I knew
the reviewers well (had worked with them for a year), trusted their senses
of humour, and had a good six months before even a beta release.  The jokes
provided an incentive to read the document primarily because they were
funny: reviewers tended to be overworked, stressed, and desperately grateful
for any break in the tedium of code and design reviews.

Carl, to answer your questions in order,

1) I don't consider this unethical or underhanded.  It's potentially explosive,
though, as Will Kelly demonstrates, so be careful who you joke with and
what you joke about.

2) How to a handle a miss?  If you mean a reviewer who misses a joke, try
having them not only sign off on the draft, but initial that paragraph.  If
you mean a joke that goes to the printers, try falling on your sword.

3) There are some dry, boring alternative techniques, such as including
specific requests for information in the draft: "Bob: when you get to this
part, give me a call, there are some issues to discuss" or somesuch.  If
you don't get the call, you know there's a problem.


Just one more opinion to add to the soup,

Michael Priestley
mpriestley -at- vnet -dot- ibm -dot- com

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html