6 Writing Tips for Developers
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.
- Use Grammarly or ProWritingAid (which I use)
- Try out the free Hemingway Editor to make your sentences easier to read
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”.
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