Why should developers study writing?

If you’ve picked up this book, then you’re probably a software developer. Furthermore, you’re someone who cares about your career. You’ve probably spent countless hours studying manuals, reading library docs, learning how to write clean code, and otherwise mastering your craft.

But you may be skeptical. There are a thousand other things you could learn. Why spend the time studying writing? Let’s walk through some of the things you might be thinking.

I’m paid to code, not to write.

In most cases, developers aren’t paid to code. We are paid to produce working software that solves a business problem. In order to do that we may need to:

Email a product manager to clarify a requirement
Instant message a designer to verify the color and placement of a call-to-action button
Document the details of an internal REST API
Submit a patch to an open-source project you use
File a bug report about a part of the software developed by another team
Provide explanatory notes about that spike in server errors on the 14th
Tweak the wording of some UI text that is confusing users, since the designer is unavailable

All of these things are run of the mill tasks for a software developer. And every single one of them is a form of writing.

I already know how to write. I did well in school.

Unfortunately, literacy, even at college or university level, doesn’t guarantee the ability to write effectively. Many degree programs place little emphasis on writing. And those that do emphasize it often encourage an academic style which doesn’t mesh well with most developer’s jobs.

Academic writing tends to value a kind of distant objectivity which can manifest as:

Unnecessary jargon
Verbose and indirect prose
Extreme formality

In contrast, most developers would benefit from making their prose clear, direct, and concise.

But I could be studying the Hoth framework instead. It’s so cool!

Yes, no matter which topic you decide to study, you will be passing up something else. But writing deserves special consideration. Why? Because writing is a durable skill.

Technology changes quickly. If you’re not careful, you can easily invest a lot of time and energy into a technological one hit wonder. Writing, though, will never be rendered obsolete by the fickle winds of technology or fashion.

Writing is also a transferable skill. If you decide to change careers and become a realtor, landscape artist, or – God forbid! – a manager, your expertise in the Hoth MVVM framework will be of limited use. But writing will remain.

But what will I get out of studying writing?

Less back and forth

We’ve all experienced out of control email threads. It starts with a vague question, is usually followed by an ambiguous answer, and before you know it, someone in another department is freaking out about a non-existent problem.

What if you could step in and make people understand? Even better, what if you could prevent the issue from escalating in the first place? That’s the power of clear and effective writing.

Fewer bugs and less rework

Sometimes we run across frustratingly mysterious bits of code. Perhaps we’ve even written some ourselves. But what’s even more frustrating is when the code is accompanied by an equally mysterious comment like, “fixes IE bug.”

What IE bug? And which version of IE?

A developer working on this code, now needs to:

Talk to the original programmer, who won’t remember anything.
Manually test to see if there are obvious bugs related to that line, which he probably won’t catch.
And perhaps make changes anyway, without knowing what he broke.

A clearly written comment would have prevented all of that.

Protect your development flow

Talking face to face is a valuable and necessary part of our jobs. But not every face to face conversation is valuable.

If you find yourself explaining certain things over and over again (perhaps because you’re an expert in a particular subsystem) then you should write it down in a public location like a team wiki. If your explanations are clear and easy to understand, you’ll have fewer interruptions messing with your development flow.

Recognition of your expertise

Perhaps you have a different problem. You have a deep knowledge of some tool, library, or system, but no one realizes it. Writing guides, tutorials, and presentations can help you achieve greater recognition, both inside and outside your company.

Greater trust from managers

Watching a software development project from the outside can be a frustrating experience. This is doubly true if you are on the hook when something goes wrong.

A developer who can clearly articulate the state of the project, without getting bogged down in technical details, is invaluable.

If you are that developer, you will quickly earn the trust of your manager and non-technical colleagues.

Improve your own understanding

“How can I tell you what I think till I see what I say?”
– E.M. Forster, Aspects of the Novel

The process of writing takes our often fuzzy and unformed ideas, and shapes them into something clear enough to communicate to others. This makes writing an excellent way to deepen our own understanding of a subject. Sometimes the improvement comes from research, but often it comes simply due to organizing our own thoughts.

What now?

Hopefully by this point you can see why studying writing is worthwhile. In the next chapter, we’ll launch into some general rules you can use to improve your writing.