RE: Code Annotation of the Week

Subject: RE: Code Annotation of the Week
From: "Janoff, Steve" <Steve -dot- Janoff2 -at- Teradata -dot- com>
To: "Laura Lemay" <lemay -at- lauralemay -dot- com>, "techwr-l mailinglist" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 12 Nov 2009 14:36:43 -0500

The unfortunate thing is that the pun itself is not very funny.

So a lot of folklore over basically an unfunny pun.

Developer humor does not always live up to the standards of humor
required by everyday folks.

But occasionally I come across a developer who has a superior sense of
humor -- sometimes at the level of professional comedians -- and I
*wish* he or she would write humorous code or at least error messages.
:)

Steve

PS - I also occasionally come across a developer who's a better writer
than most writers -- and that's always an eye-opener.


-----Original Message-----
From: techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of Laura Lemay
Sent: Thursday, November 12, 2009 10:54 AM
To: techwr-l mailinglist
Subject: Re: Code Annotation of the Week


On Nov 12, 2009, at 9:51 AM, I wrote:
> That reminds me, Janice, were you around at Sun for the Great
> tunefs(8) Scandal of 1990?


That message was just a bit cryptic. This is a story from the mists of
documentation history.

Back in the early 90's most of Sun's business was selling Unix
workstations. And a good part of the documentation load at Sun was
maintaining the existing man pages for the SunOS, the Unix OS that ran
on those machines. SunOS at the time was based on BSD. And one of the
BSD man pages was for tunefs, a command that, well, tunes a file system
(it's kind of like a defragmenter, only lower level).

In BSD Unix, since the beginning of time, tunefs man page had included
what is known as the "tuna fish" line:

You can tune a file system, but you can't tune a fish.

Some time in 1990, for the SunOS 4.1 release, an unnamed tech writer at
Sun removed that line.

I can't remember who reported it as a bug, if it was internal or
external, but it caused a HUGE FIGHT on the internal tech writer mailing
list at Sun. On one side: the argument that a joke, and a pun at that,
in Sun documentation was unprofessional, untranslatable, and
inappropriate. On the other: that this line was folklore, that it had
been in the man page forever, and that Unix history trumps documentation
professionalism. (no one knows how the line originally ended up in the
man page in the first place. There are rumors that Bill Joy, one of the
original authors of BSD, put it there.)

Eventually the folklore argument won, and the line went back in for the
next SunOS release. With it a writer included this comment in the
nroff source:

.\" Take this out and a Unix Demon will dog your steps from now until
.\" the time_t's wrap around.
.sp
You can tune a file system, but you can't tune a fish.

That comment itself contains a handful of unix puns, and its appearance
was noted with bemusement a few times throughout the years by Unix
folklorists.

SunOS was replaced altogether soon after that with the AT&T version of
Unix (what is known as SVr4), which does have tunefs but that doesn't
include the notorious tuna fish line. All current versions of Unix
based on BSD with tunefs still include the "tuna fish" line, including
HPUX, FreeBSD and MacOS X.

Laura
alt.documentation.folklore
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at:
http://www.doctohelp.com/

Help and Manual 5: The all-in-one help authoring tool. Full support for
team authoring with multi-user editing - both directly and in combination
with VSS-compatible source control systems. http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
Re: Code Annotation of the Week: From: Stuart Burnfield
Re: Code Annotation of the Week: From: Laura Lemay
Re: Code Annotation of the Week: From: Laura Lemay

Previous by Author: RE: Can we start a sentence with "or" or "and" in a manual
Next by Author: Re: Doc Design and Convention
Previous by Thread: Re: Code Annotation of the Week
Next by Thread: Re: Code Annotation of the Week


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

Sponsored Ads


Sponsored Ads