How to write better as a developer

UpdatedApril 21, 2022

•4 min read•View as Markdown

Marcin Wosinek

I'm JS developer with 13 years of professional experience. I'm always happy to teach my craft.

Comments (6)

Join the discussion

Tanish Shrivastava3y ago

I already have experience in writing, having wrote more than 100000 words for a blog over a year. But still, sometimes going back and looking at the basics is good.

I also think that formatting is a huge help in navigating the articles, lists, headings, and even blockquotes can help a lot.

Marcin Wosinek3y ago

Thanks a lot Tanish!

Rafael B. Pires4y ago

What a great text, thank you so much for sharing these valuable tips. I'm just beginning my journey as a developer and I'm trying to write about my experiences and accomplishments as I go. Your insights are going to be very useful.

PS: I've been using Grammarly for quite a long time now and it has been my day-to-day companion. I had never heard about LanguageTools though, but I'm gonna try it out for sure.

Marcin Wosinek4y ago

Thanks a lot! Keep on learning to program & keep on writing:)

When you will be applying for jobs, writing well can help you stand out. You can use to make your example project stand out: https://how-to.dev/tips-for-making-your-interview-assignment-impressive

Rafael B. Pires4y ago

Thank you for the tip! I'll read on!

Charles Moxley4y ago

Thanks a lot!I've bookmarked it!

Marcin Wosinek4y ago

Thanks!

Abodunrin Abdulsalam4y ago

Thanks for sharing these tips. It's not easy not to use a tool like Grammarly these days as it helps to spot errors in my writing quickly.

Putting pictures and writing in paragraphs are indeed useful tips to take note of when writing especially technical writeups when things can get boring easily.

Diego Ballesteros (Relatable Code)4y ago

I try to be mindful of all the tips laid out here as I write. Thanks for sharing!

Especially like the suggestion with Grammarly. Catches so many errors.

David Peng4y ago

Thank you for your sharing Marcin Wosinek!

I used Grammarly for two months, and it did help me a lot. I’m not a native speaker, and I always feel anxious whenever to publish or tweet something, even if I wrote hundreds of internal documentation and tutorials in English.

Keep reading and practice in public, that’s what I’m trying to do now. 😁

Marcin Wosinek4y ago

I'm not a native English speaker myself, and those tools help me keep a high quality of writing:) I'm sure they are useful for native speakers too - my writing in Polish if far from perfect too:)

More from this blog

Changes in programming made possible with AI

I’ve been working in programming for the last 16 years. Let’s see what changes I see in our industry that are enabled by generative AI. Rapid prototyping The last few months, I’ve been working on a set of WordPress plugins, related to event organizat...

Dec 22, 20252 min read

Advantages of unit testing—with examples in Jasmine

Writing unit tests takes time and effort. Nonetheless, many teams insist on writing them anyway—that’s because of the benefits they bring to a project. Those benefits are mainly the following: fast feedback—unit tests speed up each iteration of twea...

Feb 15, 20245 min read

Advantages of unit testing—with examples in Jasmine

Pure functions and basic tests in Jasmine

Pure functions are the perfect case for unit testing. For a given input, we always expect the same output—there is no internal state involved. Let’s take a look at a few examples and some simple tests that check if the methods work as expected. Jasmi...

Feb 8, 20245 min read

Pure functions and basic tests in Jasmine

How to prepare for a job interview

Let’s say you have a job interview in a few days. How should you prepare for it so that you can make an informed decision about joining the company, as well as make sure that your interests are taken care of? Prepare your questions An interview is a ...

Feb 1, 20244 min read

How to build a demo project

Creating example projects is a common way of showing your skills to potential employers. Let’s take a look at what’s important to keep in mind when building personal projects with an eye toward impressing prospective employers. Simplicity Building ap...

Jan 25, 20248 min read

How to dev

164 posts

Articles about programming. JavaScript and general advice for beginners in the industry.

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.

Image description

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.

Image description

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.

Image description

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.

Image description

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

Image description

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.

Command Palette

Comments (6)

More from this blog

Break your text into paragraphs

Use some of the available stylings

Make it easy for the reader

Read and edit what you wrote

Use automated tools to improve your writing

Grammarly

LanguageTools

Become the best friend of your readers