Software engineers should write

In elementary school, there were “math kids” and there were “English kids”. You were classified by the other kids’ impression of your prowess in each subject.

I was a math kid. So I majored in computer science and set off to be a software engineer. Along the way, though, the “math kid”/”English kid” designation never really wore off. If anything, it got stronger. The engineers I meet today cringe at the thought of writing an essay. And the writers I meet cringe at the thought of writing code.

What a shame! An engineer who writes code should also write essays.

Software engineers should write because it promotes many of the same skills required in programming. A core skill in both disciplines is an ability to think clearly. The best software engineers are great writers because their prose is as logical and elegant as their code.

Code and essays have a lot more in common. Both begin as a blank slate and an idea, then end as a discrete product for an intended audience. The product is a sequence of logical statements, bundled into modular units– whether it be functions or paragraphs. Like good prose, good code is concise (think “expressive”). Bad code wastes CPU cycles; bad essays waste brain cycles.

When closing in on a finished product, the engineer feels the same uneasiness as the weary writer. As with essays, software never quite feels “done”. It nudges for more of the engineer’s time: another feature to be built, another module that needs refactoring. He/she’s afraid it won’t be the best representation of his/her work. Oh well. Ship it.

Software engineers should write because our craft is increasingly collaborative. Open source projects invite worldwide participation, while industry products often require an army of engineers. (Google Maps has 1100 full-time employees!) Good writing– whether it be in a GitHub comment, code review, or technical documentation– facilitates clear, concise communication for projects like these to move forward.

Even if a project doesn’t require communication, writing about software in general promotes learning and important discussions. We don’t have to learn from RFC specs and technical manuals, thanks to tutorials written by other engineers. In technical discussions, only so much opinion can be stuffed into a Hacker News comment or a tweet. The rest begs to be channeled into a blog post.

On the topic of blog posts, put some time into them. Good writing takes time. It’s natural to write a “sloppy copy” off the bat, then improve the quality over several revisions. If you feel too busy to blog, at a loss for topics, or worried about your opinion being on the public record, give Steve Yegge’s You Should Write Blogs ten minutes of your time. Even if it doesn’t convince you, I think you’ll enjoy the read.

Software engineers should write because they might actually enjoy writing. Many of us are motivated by the potential for our software to have “impact”, to make a difference in people’s lives.

In the same way, writing is a powerful vehicle for impact. The blog post on management helps a manager invigorate his team with motivation. The tutorial on programming sparks a student’s interest in computer science. The essay on career advice inspires a graduate to pursue a new career path.

Even if nobody reads your essay, writing it will make an impact on you. It will clarify your opinion on a topic and strengthen– or even weaken– your beliefs. The process alone of putting jumbled thoughts into concrete words is valuable.

Writing offers the same sense of impact that motivates an engineer to write software. Combine this with how it promotes skills useful in software engineering and facilitates collaboration, then suddenly writing appears to be a worthwhile activity.

Even for the “math kids”.


Software ⋅ December 2014

Hacker NewsRedditPortuguese