This is the introduction to The Best Software Writing I, Selected and Introduced by Joel Spolsky, now in bookstores.

New York City is a blast.

Just the other day, as I was walking the four blocks from my office to the subway entrance, interesting things kept happening.

Not really interesting things, just modestly interesting things.

So, for example, some guy was running down the sidewalk frantically, looking very much like a character in an R. Crumb comic, flapping his arms broadly and making chicken sounds. Running isn’t the right word. He was kind of pratfalling repeatedly and then catching himself right before he hit the ground.

Then a taxi turning the corner nearly knocked over an old man who was crossing the street a little bit too slowly for the taxi driver’s taste.

A couple of chubby, red-faced out of towners asked me if there was a bar anywhere nearby. (There was. We were in front of it.)

Someone was handing out little advertising cards at the entrance to the subway. Of course, the inside of the subway station was completely littered with the cards because everybody who took one immediately hurled it on the ground as violently as you can hurl a four by six postcard. I almost slipped on one on the steps down.

Modestly interesting stuff, but quite forgettable in New York.

The next day I was talking to one of the summer interns we just hired. For some reason, this year’s summer intern class consists of 75% people who are either from Indiana or who went to school in Indiana. Indiana, for those of you not familiar with our American landscape, is somewhere in the middle, a state of farms, wholesome colleges with corn-fed basketball-playing kids, Norman Rockwell towns, and the occasional rust-belt hellmouth industrial city gasping its last breath. (As I write these words I brace for the slew of angry letters from the Indiana Department of Tourism and Infrastructure promoting the exciting cultural scene, the many picturesque lakes, the world-class telephone system, and the variety of ethnic restaurants. You might find a Mexican restaurant and an Italian restaurant on the same block!)

Anyway, the intern said he had never lived in New York City, and asked me what it was like. I didn’t really have a good answer, but I said, “New York is the kind of place where ten things happen to you every day on the way to the subway that would have qualified as interesting dinner conversation in Bloomington, Indiana, and you don’t pay them any notice.”

Feeling smug with myself, I pulled down an atlas from the bookshelf to find another state to insult.

Anyhow, I can’t remember why I told you that story.

Oh, wait, yes I can, but first I have to tell you another story.

A few months ago, I got a review copy of a book from another publisher, other than the publisher of this book, who will remain anonymous, and the book will remain anonymous, and the author will remain anonymous, because I’m afraid I just have nothing good to say about said book.

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.”

Anyway, I called up the editor of the book that they wanted me to praise, and said I couldn’t, in good faith, recommend a boring book without any stories in it, even if it was 100% correct and otherwise well-written. I think they hate me now.

 

So be it.

 

The software development world desperately needs better writing. If I have to read another 2000 page book about some class library written by 16 separate people in broken ESL, I’m going to flip out. If I see another hardback book about object oriented models written with dense faux-academic pretentiousness, I’m not going to shelve it any more in the Fog Creek library: it’s going right in the recycle bin. If I have to read another spirited attack on Microsoft’s buggy code by an enthusiastic nine year old Trekkie on Slashdot, I might just poke my eyes out with a sharpened pencil. Stop it, stop it, stop it!

And that’s why when Gary Cornell suggested this book, I leapt at the idea. It would be a chance to showcase some of the best writing about software from the past year “or so.” The original idea was to make it an annual, so the volume you’re holding would be “The Best Software Writing of 2004,” but there were a bunch of great articles from 2003 that we wanted to include, and we were afraid bookstores would return it at the end of the year if there was a date in the title. I solicited nominations from the faithful readers of my website, Joel on Software, and selected the final stories myself, so the blame for what’s included and what isn’t included is entirely my own, but full credit for really incredible writing in a field that doesn’t normally get any goes to the contributors.

 

The Best Software Writing I is now available. It includes:

Ken Arnold – Style Is Substance 
Leon Bambrick – Award for the Silliest User Interface: Windows Search 
Michael Bean – The Pitfalls of Outsourcing Programmers
Rory Blyth – Excel as a Database
Adam Bosworth – ICSOC04 Talk
danah boyd – Autistic Social Software
Raymond Chen – Why Not Just Block the Apps That Rely on Undocumented Behavior?
Kevin Cheng and Tom Chi – Kicking the Llama
Cory Doctorow – Save Canada’s Internet from WIPO
ea_spouse – EA: The Human Story
Bruce Eckel – Strong Typing vs. Strong Testing
Paul Ford – Processing Processing
Paul Graham – Great Hackers
John Gruber – The Location Field is the New Command Line
Gregor Hohpe – Starbucks Does Not Use Two-Phase Commit
Ron Jeffries – Passion
Eric Johnson – C++ — The Forgotten Trojan Horse
Eric Lippert – How Many Microsoft Employees Does it Take to Change a Lightbulb?
Michael “Rands” Lopp – What to do when you’re screwed
Larry Osterman – Larry’s Rules of Software Engineering #2: Measuring Testers by Test Metrics Doesn’t
Mary Poppendieck – Team Compensation
Rick Schaut – Mac Word 6.0
Clay Shirky – A Group is its Own Worst Enemy
Clay Shirky – Group as User: Flaming and the Design of Social Software
Eric Sink – Closing the Gap
Eric Sink – Hazards of Hiring
Aaron Swartz – PowerPoint Remix
why the lucky stiff – A Quick (and Hopefully Painless) Ride Through Ruby (with Cartoon Foxes)