How to write better as a developer

#beginners #programming #writing

Recently, I had two programming friends point out to me the importance of writing skills. It makes sense to pay attention to what they say because:

one runs an online product company,
and the other jumped from a bootcamp graduate to a lead developer within just a few years.

Let’s look at a short guide to improving your writing in your day-to-day job.

Break your text into paragraphs

The first step to improving your writing is to break your thoughts into digestible pieces. Instead of dumping a massive wall of text, put some space between sentences as your focus goes from one thing to another. Breaking things into paragraphs will make your text more economical, less overwhelming, and easier to read. Smaller chunks preserve your reader’s mental energy.

Don’t write like this.

Use some of the available stylings

Most systems where you will send your message have some styling available. You can expect to have at least:

bold,
italics,
headers,
underscores, or
strike through

Using these will make the quick parsing of your text more manageable. You can easily direct readers' attention to the most important parts, making it more likely that you will achieve the goals of the text you’re writing.

Decoration makes a difference.

Make it easy for the reader

There are two things that you can do to make the lives of your readers easier:

use HTML links, and
include images in the text to convey your message or explain the issue

These editing options are not always available. For example, in Slack, I’m always annoyed that I cannot put images between paragraphs.

When these options are available, using them significantly improves the readability of the text. One can see pictures immediately after they are referenced in text, and massive links are not breaking the flow of text.

This is essential in working with tickets. For example, in Jira, if you just add an image to the issue, it can still be clear when you have only one there. But as soon as the team adds five other pictures in comments, it can get confusing fast. Putting images inside text makes is clear which is relevant where.

The web has had links since 1991 and images since 1992. Let’s use them!

Read and edit what you wrote

A bit of editing can improve the first version of your text a lot. If you can, it’s best to save a draft and come back to edit later—maybe after some break or even the next day. At a minimum, rereading the whole text before publishing should allow you to tweak the way you say things to improve the reader’s overall impression of your text.

Editing is the key to a good reader experience. Doing it yourself should be good enough for most things you write, and it’s a basic courtesy for your readers.

Use automated tools to improve your writing

Dictionary checks are not the only ways machines can improve your writing. Nowadays, there are advanced tools available that can take care of things like:

catching correctly spelled words used in wrong places (as I do all the time with ‘then’ and ‘than’)
marking passive voice— using active voices makes your writing more vivid
reorganizing sentences to be easier to read — at least according to an algorithm

If you are serious about your writing, you should look at some available applications.

Grammarly

If you get similar YouTube ads, you have definitely heard about them. I’ve been using it since July 2021, and I’m pleased with it. It was the first serious quality improvement I implemented on my blog.

Pluses:

it understands the context of words and suggests changes accordingly: it will tell you if you mean “it’s” or “its”
it points out overused words and suggests other options
in the paid version, it can suggest restructuring of the sentence

Minuses

lack of support for languages other than English
the Firefox plugin on Mac struggles with Google Docs
the paid version is 144$/year, which is more than competitors
you can hear about security and privacy issues. From what I’ve searched, the most significant security breach was in 2018, and they fixed it quickly. The privacy issue is related to all processing happening on the company servers—so you need to trust the company to follow its terms of service.

LanguageTools

Pluses:

it supports more languages (grammatical correction in 5 European languages), more basic support for 20 languages, and more
you can self-host the free version, so your data stays entirely under your control

Minuses:

less marketing—I only found them when I start asking around

Become the best friend of your readers

All these tips boil down to thinking about the people who will read your text. Your job is to make it easy for them to read it. It calls for being more empathetic. Putting in the extra effort should pay well for you: often, your readers are your boss or people who have an impact on your career. Even when you write for your colleagues, most likely there will be many of them—and it will serve you well to build a reputation as an efficient communicator.