Fog Creek Software
Discussion Board

Being funny in specs

Some time back, Joel mentioned that the number one way to make your specs interesting was to make them funny.

I don't really agree with this. Now, don't get me wrong, all my favourite computing books have got a large dose of humour in them, but I can't see this applying to specs.

For one thing, one man's sense of humour is another man's irritation. I am sick and tired of coming across stupid in-jokes in code and documentation that some ex-developer made three years ago and isn't funny when I'm trying to nail down a bugfix, or trying to find out how a particular feature actually works. I don't think most developers have got the ability to be funny across a wide audience of readers and a long period of time.

I don't think a lack of humour applies to books because I read those more at my leisure, not to find out some vital piece of information so I can make progress.

My alternative method for making specs interesting is to not waffle, keep sentences short and understandable, put in plenty of whitespace around paragraphs, and to put pictures around the text wherever appropriate. (Actually, that's one of my favourite bits of this site, where articles are broken up with almost random pictures thrown in).

What do you lot think? Has anybody tried fitting large doses of humour into their specs? What are the results?

Better Than Being Unemployed...
Thursday, June 26, 2003

I once tried a somewhat foolish joke as a footnote in some documentation involving an accounting system. I wrote the text along the lines of:

You need to define the euro currency* in the system....

*Preferrably EUR, but you could set it to another value on
April fools day.

Noone noticed this.

So, I guess specs and documentation does not get read :)

Thursday, June 26, 2003

I always look funny in specs.

Thursday, June 26, 2003

Specs suit some people, but others are better off with contacts.

Steve Jones (UK)
Thursday, June 26, 2003

I don't know that "being funny" was to be taken so literally.  If I'm writing a spec, I don't think I'd go so far as putting jokes in the actual spec:

e.g. This pointer should be set to NULL before calling this function.  All who break this rule will be found and killed.

I think a more subtle form of humor (the kind I remember seeing when I read the article a while ago) is to use the examples as an outlet.  This can be very effective to help the reader understand your (potentially mundane) examples.

An example I saw yesterday while doing some Carbon programming can be found here:

Using the Simpsons as sample data adds levity to the situation, I believe.

Like Mary Poppins sang: "Just a spoon full of sugar makes the medicine go down."  It seems to apply here too, and I agree that using a bag of sugar would probably upset someone down the road.


Chris L
Thursday, June 26, 2003

It appears my link did not work effectively.  Try clicking "Creating Property Lists" near the end of that page.

Sorry for that,

Chris L
Thursday, June 26, 2003

[nod] Examples are the best place to use humor.

"Tony Soprano wants to use Mapquest to keep track of where all the bodies are buried..."


Thursday, June 26, 2003

Most specs read like "and then a miracle occurs" anyway, and I always find that funny.

Joe AA
Thursday, June 26, 2003

I like the word "automagically."

Leonardo Herrera
Thursday, June 26, 2003

the deeper issue is that most people who write specs do not have a very good sense of humor. so "being funny" in the spec is bound to fail.

Thursday, June 26, 2003

I've seen a lot of humour in specifications.

The problem is, it was unintentional.

On a related note - does anywhere know a software development workplace in North America where people have an actual sense of humour?  Are you hiring?!

Most of the people I work with are terribly, terribly serious. It's depressing. Not to take credit away from the very small handful of others there who do have a sense of humour - great people, all of them; I'm talking about the workplace culture in general.

I'll give you a recent example:

One of the guys in our open-plan office (yes I hate them too - that's a whole 'nother thread) happened to move to a desk close to mine. This gentleman had an unusually large collection of office supplies which he took great care to arrange on his shelf, line up very precisely for passers-by to see.

So I decided to help.

I printed up a large and very official looking sign the read: "National Museum of Office Supplies", complete with a federal government logo that I found on a web site.  I also created little placecards for each item in the display. For example:

  "This stapler was used to staple the declaration
    of independence on August 2, 1776."


  "This box of staples was recovered from the
    wreck of the Titanic, which sank on April 15, 1912
    with a tragic loss of office supplies."

And so on.

Some of the guys absolutely cracked up laughing. The others? They didn't even crack a smile. The guy who's desk it was didn't even acknowledge that the "display" existed. Which to me was bizzare, because I would have expected some retaliation at least!

I'm fairly sure this has to do with ethnic/cultural issues. I'm an Aussie. I won't say what ethnicity the ones who don't laugh are - but suffice to say, it's clear that humour is not part of their culture. It's quite depressing being in a work place like that.

Thursday, June 26, 2003

Some people just don't have a sense of humor, and the sad thing is that they don't KNOW that they don't have a sense of humor. They're always muttering, "grr, why can't people be PROFESSIONAL around here."

Joel Spolsky
Thursday, June 26, 2003

I've been at this company for 9.5 years and have seen it change from a place where humor was common (filling the cab of a salesguy's pickup truck full of packing peanuts was always popular) to a far more "serious" environment.  Very sad.

I attribute it to the company going from privately held to a public company.  Once that change happened it was like a lightswitch.  It got even worse once there were layoffs. 

Like an earlier post in this thread pointed out, some people don't appreciate or can misinterpret attempts at humor.  I'm less likely to crack a joke in a crowd, just keeping my head down and trying to not give anyone any reason to single me out if there are ever more layoffs.  (This probably says more about my own insecurities than intended).

I miss the days when we would suspend a fully decorated Christmas tree upside-down from the ceiling. 

And I wish I worked with Aussie Rob who set up the muesum on his neighbor's desk. (BTW, I do think it is a cultural thing... you Aussies are cracked!  [grin])

Rob H
Thursday, June 26, 2003

Well, having dissed humour in specs earlier, I've just been reviewing one I did about six months ago, which includes a mockup dialog for Mr Terrence Q Testward of Foo Suppliers, Foohampton, Fooshire.

I laughed - your mileage may vary.

Better Than Being Unemployed...
Thursday, June 26, 2003

"I've just been reviewing one I did about six months ago, which includes a mockup dialog for Mr Terrence Q Testward of Foo Suppliers, Foohampton, Fooshire."

Yeah, this is what I meant. "Foo" is not humor.

Thursday, June 26, 2003

...and clam's the guy Joel was referring to. [grin]

I think "Foohampton, Fooshire" is pretty funny.


Thursday, June 26, 2003

A boss wouldn't allow On Error Goto HELL.  After several private meetings I finally talked it into her, er, talked her into it.

Our team of programmer
Thursday, June 26, 2003

Hmmm..  I work for a smaller, public company where there is still a good sense of humor.  The official, unofficial, policy is that we are to play hard but not expose the company to any liability.

I think that humor is often dependent on how close and gelled the team is.  If a team can jokingly have a scapegoat for problems (where the scapegoating is clearly teasing and not malicious), that's funny for everybody.  If somebody you don't have much of a working relationship with is trying to be funny, there's less context to your humor and it isn't as amusing.  Then you can put in-jokes in the spec and everybody will find it amusing.

This gets into the science of humor, but the gift of a comedian is not that he is funny.  It is that he is funny to a large group of people.  Put your average person on the stage and he'll be funny to his friends and boring to everybody else.

Flamebait Sr.
Thursday, June 26, 2003

Yeah, the examples are where its at in specs. The humour is there to bribe people to read it, but you need to be clear about the real points.

As for cultural differences in the workplace pertaining to humour appreciation ... well people have to fit in to the workplace first, to find out how permissive it is with respect to it. If you have a lot of staff turnover, you will end up with a lot of people who don't know each other well and don't fit in enough to express their humour. A lot can come down to the personality of the people they report to, or whether there is an upstairs-downstairs mentality (management & the serfs).

But yeah, some people just don't see the humour in things anymore ...

Thursday, June 26, 2003

Rob H,

I agree about the shift from private to public ownership. My fun/productive workplace was purchased by GE several years ago. It was horrible. Fortunately, it spurred me to quit and find a job in another industry where I work banker's hours and make 3x as much.
BUT, I work for a very large corp. now, and there are pockets of fun here and there. I'm in a 10-person group (only 2 of us are programmers, the rest are financial people) with an awesome dynamic. No quarter given, and none asked as far as practical jokes, good-natured put downs, etc. are concerned.

Rob Too
Friday, June 27, 2003

I want an office full of "Rob" types. I just love the museum notation cards. Perfect.

People are right when they say it requires chemistry for humor to work. And if you have been together for a while, you tend to have some shared experience to play off that can make this even easier.

But it isn't just humor. You need the chemistry to be there in order to be productive as well. Without it, you don't get people who want to come to work or do much work while they are there.

And for the record, most things in comments are just not funny. The one exception I've seen was someone randomly inserted "/* rosebud */" in the middle of a program. I don't know why, but it just cracked me up.

Friday, June 27, 2003

Specs should be written entirely in rhyming couplets.

At sporadic intervals, to hilight an important point, the rhyme should be a terribly forced off-rhyme.

Now that's good fun.

Gustavo W.
Friday, June 27, 2003

Specs are like the Tao,
To flow, they must be complete
While being concise

And for this reason
The haiku is the perfect
Form for writing specs

Friday, June 27, 2003

*  Recent Topics

*  Fog Creek Home