Show, Don't Tell

I picked up a copy of The Best Software Writing I: Selected and Introduced by Joel Spolsky. It's essentially just a collection of Joel's favorite blog entries from the last few years. But it's Joel, so you know they're going to be good ones. In the introduction, he explains why he's so enthusiastic about blog writing: it encourages the simple, but powerful use of show, don't tell:

The publisher wanted to get a quote from me to put on the back cover talking about how wonderful his book was. Normally I'd be happy to do that; I'm a complete publicity slut and will do just about anything to get my name in front of the reading public. My hope is that if I do this enough, telemarketers who call me at home will be able to pronounce my name.
The book started out looking promising. It filled a real need. I remember several times standing in bookstores desperately trying to find a book on the very topic, but there was nothing to be found. So I started reading the manuscript full of high hopes.
Bleah. I could hardly bear to keep reading. The author kept saying smart and interesting things. He even wrote clearly. But the book was thoroughly, completely, boring. And worse, it was completely unconvincing.
The author had violated the number one rule of good writing, the "Show, don't tell" rule. There was not a single story in the book. It was chock full of sentences like "A good team leader provides inspiration by setting a positive example." What the eff?
Pay attention. Here's the way to say "a good team leader provides inspiration by setting a positive example" without putting your audience to sleep:

For a few months in the army I worked in the mess hall, clearing tables and washing dishes nonstop for 16 hours a day, with only a half hour break in the afternoon, if you washed the dishes really fast. My hands were permanently red, the front of my blouse was permanently wet and smelly, and I couldn't take it any more.
Somehow, I managed to get out of the mess hall into a job working for a high-ranking Sergeant Major. This guy had years of experience. He was probably twenty years older than the kids in the unit. Even in the field, he was always immaculate, wearing a spotless, starched, pressed full dress uniform with impeccably polished shoes no matter how dusty and muddy the rest of the world was around him. You got the feeling that he slept in 300 threadcount Egyptian cotton sheets while we slept in dusty sleeping bags on the ground.
His job consisted of two things: discipline and the physical infrastructure of the base. He was a bit of a terror to everyone in the battalion due to his role as the chief disciplinary officer. Most people only knew him from strutting around the base conducting inspections, screaming at the top of his lungs and demanding impossibly high standards of order and cleanliness in what was essentially a bunch of tents in the middle of the desert, alternately dust-choked or mud-choked, depending on the rain situation.
Anyway, on the first day working for the Sergeant Major, I didn't know what to expect. I was sure it was going to be terrifying, but it had to be better than washing dishes and clearing tables all day long (and it's not like the guy in charge of the mess hall was such a sweetheart, either!)
On the first day he took me to the officer's bathroom and told me I would be responsible for keeping it clean. "Here's how you clean a toilet," he said.
And he got down on his knees in front of the porcelain bowl, in his pressed starched spotless dress uniform, and scrubbed the toilet with his bare hands.
To a 19 year old who has to clean toilets, something which is almost by definition the worst possible job in the world, the sight of this high ranking, 38 year old, immaculate, manicured, pampered discipline officer cleaning a toilet completely reset my attitude. If he can clean a toilet, I can clean a toilet. There's nothing wrong with cleaning toilets. My loyalty and inspiration from that moment on were unflagging. That's leadership.

See what I did here? I told a story. I'll bet you'd rather sit through ten of those 400 word stories than have to listen to someone drone on about how "a good team leader provides inspiration by setting a positive example."

True enough. And even if you don't entirely agree that Joel's choices are "The Best Software Writing"*, they're still pretty darn good:

Style is Substance, Ken Arnold
Award for the Silliest User Interface: Windows Search, Leon Bambrick
The Pitfalls of Outsourcing Programmers, Michael Bean
Excel as a database, Rory Blyth
ICSOC04 Talk, Adam Bosworth
Autistic Social Software, Danah Boyd
Why not just block the apps that rely on undocumented behavior?, Raymond Chen
Kicking the Llama #4, Kevin Cheng and Tom Chi
Save Canada's internet from WIPO, Cory Doctorow
EA: The Human Story, ea_spouse
Strong Typing vs. Strong Testing, Bruce Eckel
Processing Processing, Paul Ford
Great Hackers, Paul Graham
The Location Field is the New Command Line, John Gruber
Starbucks Does Not Use Two-Phase Commit, Gregor Hohpe
Passion, Ron Jeffries
C++ - The Forgotten Trojan Horse, Eric Johnson
How many Microsoft employees does it take to change a lightbulb?, Eric Lippert
What To Do When You're Screwed, Michael "Rands" Lopp
Larry's rules of software engineering #2: Measuring testers by test metrics doesn't, Larry Osterman
Team Compensation (pdf), Mary Poppendieck
Mac Word 6.0, Rick Schaut
A Group Is Its Own Worst Enemy, Clay Shirky
Group as User: Flaming and the Design of Social Software , Clay Shirky
Closing the Gap, Part 1, Eric Sink
Closing the Gap, Part 2, Eric Sink
Hazards of Hiring, Eric Sink
Powerpoint Remix, Aaron Swartz
A Quick (and Hopefully Painless) Ride Through Ruby (with Cartoon Foxes), why the lucky stiff

You can save your $22.49 with a few deft mouse clicks, but I think it's reasonable to have these entries in book form, with Joel's typically insightful introduction for each entry. The book works quite well as a survey overview of the outstanding blog content that most people still don't even know is out there.

* For example, I couldn't even bring myself to finish reading Paul Ford's rambling, incoherent novella Processing Processing. Good Lord. I'd also drop the last one with the foxes on Ruby. It was neither funny nor particularly instructive. I don't mean to be overly negative; these are definitely the exceptions. The rest are quite good..