6 Writing Tips for Developers

February 28, 2021 · 2 min read
Woman typing on a MacBook
Photo by Christin Hume on Unsplash

As developers, we write a lot.

We write documentation, proposals, issues, RFCs, emails, ….

You name it.

And with more and more companies offering remote work, writing is getting more and more important.

If we're writing a lot, and if writing is so important, how much time do we spend on improving that skill?

Here are 6 tips that help you improve your writing, from blog posts to emails.

Write Simple and Clear

No fancy words.

Use a simple sentence structure. Subject, verb, object.

Avoid passive.

Explain acronyms on first use within a text.

Short Sentences. Short Paragraphs.

Make your sentences short. Cut them in half. And express only one thought per sentence.

Keep paragraphs to three sentences.

It's like web design: white space is your friend.

Thanks to For The Interested by Josh Spector. His newsletter is jam-packed with excellent writing advice.

Write, Then Rewrite

Whatever you write, you don't get it right on your first draft. Just as with code, you create the best writing from something that works through refactoring.

Something that works is a text that contains everything you want to say. Refactoring means rewriting your text to improve it.

Write With A Specific Person In Mind

Writing works best when you know who you're writing for. Every reader has a different experience with the topic you write about. You explain things differently to an experienced programmer than to an intern straight from college.

Everyone is at a different point on their journey.

Therefore, always consider who you're writing for. How much pre-existing knowledge about that subject do they have? What do you need to say explicitly? What can you omit?

Automate The Tedious Bits

When developing systems, we automate stuff that's repetitious. We can do the same with written words.

Automate checking for typos and sentence structure.

Sound Conversational

When writing, you want the reader to feel as if you're talking to them.

Use “you” and “we” often.

Keep it friendly. “You can”, instead of “you must”.

Writing advice by Gary Provost. Vary your sentence length to keep your reader engaged. Source: Twitter @misscrisp

Writing is a serious career skill. Try out the tips above for clearer communication.

“Being a good writer is 3% talent, 97% not being distracted by the Internet.” — Anon