Communication breakdown

by Andy Lester

I moved into a new house last week. The whole time we prepared for the big day, my project management gears were in overdrive. We had day-by-day checklists stuck on the walls of what had to be done each day, with the movers packing us up on Tuesday, two closings on Wednesday and then moving in on Thursday. Everything went smoothly until last night, when I went to set up the network. I'd put all cabling, keyboards, mice, routers, etc into one box, labeled it "COMPUTER -- OFFICE -- BASEMENT" and put a big star on it, so that it would wind up where I would need it.

Too bad I didn't tell the movers.

I spent a couple of hours last night (hours that I should have been spent writing for an upcoming ORA book) trying to find the box. Finally I found it, in the far back of the storage space under the stairs, behind a couple of Rubbermaid containers of maternity clothes.

All this hassle with moving day got me thinking about problems with modules, specifically WWW::Mechanize. Every few days, I get email from someone with some Mechanize question, and they include sample code. Most of the time, that sample code is missing some obvious shortcuts, or what I would consider the Right Way To Do Something. For example:

my $response = $mech->get( "" );
die unless $response->status == 200;

is better written as

$mech->get( "" );
die unless $mech->success;

Why don't people use the convenience methods I built in? I assume it's because they're unaware of their existence. So how do I let people know about them?

And then, in one of those great little synchronicities of life, I went through the last week of the perl5porters mailing list, and it seems quick refs and cheat sheets are popping up all over the place. Iain Truskett wrote a
Perl Regular Expression Reference, and Juerd Wallboer has a Perl 5 cheat sheet both of which will be in perl 5.8.1's distro, and Casey West just showed me his
cheat sheet for the Test::More module.

I see the cheat sheet as different, and in some ways better, than the FAQ. The FAQ is often long and windy, but rarely gives one the feel of how to use the software. The cheat sheet puts everything within a quick eyescan.
The cheat sheet isn't a new idea, of course.
O'Reilly's been binding them as pocket references for years. Andrew Ford has created reference cards for C, Emacs, Apache and mod_perl.

Here's hoping that other software authors pick up the ball and include cheat sheets. I guess I better write one for WWW::Mechanize to set a good example... :-)

How do you make sure people are aware of how things work in your projects?


2003-08-12 10:42:34
Noticed when searching for particular language cheat-sheets I got a lot more hits for the singular "cheat sheet" than the plural.

...and a double angry eyebrow to the folks who wrap marketing material up under the heading "cheat sheet"