Writing good computer code is like writing a good story or email

Writing good computer code is like writing a good story or emailWriting is hard. It doesn’t matter if it’s computer code, a story, or an email. And the interesting part is, no matter what you’re writing, it’s hard for the same reason. It’s tough to transport yourself from the mind of a writer to the mind of a reader.

I recently listened to an older episode of The Tim Ferris Show. Tim interviewed David Heinemeier Hansson, or DHH as he’s commonly known. DHH is a highly regarded coder. He created Ruby on Rails, and he’s the cofounder of Basecamp.

In the conversation, DHH mentioned that people who write clean code tend to write well generally. His comments got my mental wheels turning.

Your brain just works differently when you’re writing

Like I said above, I think the hardest part of writing is being helpful to the reader. But why is that so difficult?

When you write, you tend to rely on some pretty rich context. You’ve been pondering the topic you’re writing about. If it’s computer code, you know the problem you’re trying to solve. If it’s a story, you have an idea of the characters and the conflict. If it’s an email, you know what response you’re looking for.

You start pretty far along the curve. That’s the reason you feel compelled to write.

Your familiarity with the topic is a fantastic advantage. It springboards you into the meat of the topic. You don’t have to waste time with background. You can quickly move into solving the problems that made writing worth the effort in the first place.

You’re trying to get words onto paper. You’re trying to minimize effort and distraction. You’re in first draft territory. And as Ernest Hemingway said,

The first draft of anything is shit.

It’s a real struggle to immediately empathize with readers

In order to write, you had to cross some motivational threshold. You’re sufficiently inspired to take on the hard work of writing. And your motivation hurts you, in a strange way, when it comes to empathizing with readers.

As a writer, you care more about your writing than almost any reader will. Again, I’m talking just as much about computer code and email as I am traditional stories. They’re your words. It’s nearly impossible to get someone else to care as much about them as you do.

And that’s okay. It’s perfectly natural. But it puts you at a considerable disadvantage. You have to introduce some distance. Not just between you and your words. But between you and the problem you’re trying to solve. That’s how you approach what you wrote as a reader.

My number one editing tip, to others and myself, is to wait. Create a draft and then wait. Go away. Go to sleep. Do something else. Release the problem from your mind.

When you come back to the problem, you’ll have new perspective. It’s the best chance you’ll see what you wrote the way a reader would.

I’ve done that multiple times with reasonably simple emails. If it’s not urgent, I’ll do my best to draft a decent email. Then I’ll save it and look at it in the morning. And sometimes…what I wrote the first time was total gibberish. It made sense to me in the moment. It made sense given what had been on my mind all day. But when I wasn’t immersed in that particular question, what I wrote seemed almost completely inaccessible.

You edit computer code you like edit stories or emails

The challenge is the same, no matter what you write. You have to remove everything that makes a reader’s life harder.

The strange part with computer code is, the reader is often you. You might work on a piece of code on and off for weeks, months, or years. You’ll revisit it, sometimes frequently, sometimes not. And you have to find a way to pull yourself back in, even if it’s been a while since you’ve written.

It’s why you want to cut out as many lines of code as you possibly can. The more lines, the more sources of distraction. You’re burying the heart of your solution. Peel away as much as you can, leaving only what’s strictly necessary to solve the problem.

The same thing happens with stories and emails. With a story, you want to entertain. Or to provoke a thought. Or just generally initiate some sort of change in the reader. Anything that distracts from the change you want to inspire has to go.

Likewise with email. You know what answer you’re looking for. You know what request you’re trying to make. You know what information you’re trying to share. Strip out everything that interferes with your mission.

Plenty of stuff might have made great sense when you wrote it. It was part of the storm going on in your head. It was the prologue to the solution you eventually found. Including it was natural. It kept the writing flow going.

But for a reader, it’s useless. It’ll open more questions than it answers. You have to keep whittling down, leaving only what makes sense and moves you toward a successful engagement.

Don’t treat any writing as throwaway writing

I suppose my one big piece of advice here is to take all writing seriously. Even your one line emails. Even the five line script you wrote to post-process some experimental data.

Take it all seriously. Know what you’re trying to accomplish. Know who’s reading. Try your best to separate what’s important to you, as a writer, from what’s important to a reader.

There’s a scarcity of good writing. And I’m not just talking about books and screenplays and stuff that most people think about. There’s a scarcity of nicely written emails. There’s a scarcity of nicely formed project status updates, and nicely crafted presentation slides.

Simply taking writing seriously is well over half the battle. We’re not all going to be Ernest Hemingway or Stephen King. (I’m certainly not.) But even just a little pride in your writing can make a big difference.

Deliberate writing can be one of your competitive advantages. It’s the kind of thing that compounds over time. It becomes part of your reputation. And best of all, it’s noticed most by the people whose attention you want.

Leave a Reply

Your email address will not be published. Required fields are marked *