Being a developer requires you to communicate with others. Even senior developers are expected to write a big chunk of the paragraphs for different purposes, outside their favourite code editor. By the way, I will tell you one secret — senior developers write even more compared to more junior developers, due to the amount of the knowledge which is required to be shared with the team. Personally, I would say that being a full-time developer on daily basis I mainly reply to emails, write code comments, update documentation, clarify changes I've done in my latest pull request and so on.

In the majority of the cases, developers are bad at writing. This is especially true for the situations where the language which is required for communication is not the native one. In my case, English is not my native language and I used to struggle a lot with writing. This is the reason why I've started reading a lot of about techniques how to improve my writing skills.

Writing is a permanent expression of your intent and ideas.

In early stages of my career, I used to have difficulties in communicating with long email chains when I've joined a big organisation. I often got the point, when it was either hard to express my thoughts or I thought that it's just pointless to convince people through the email. Year after year, I was becoming a better writer, because I've spent a bit of the time reading books and doing courses as well as started to write blog posts more often. The purpose of this blog is to share several simple steps, which are supposed to help you out to express your thoughts in a better way.

• Write it down
• Revise it
• Polish it

I highly recommend you to read The Senior Software Engineer book which gave me a lot of inspiration to write this blog post.

Write it down

Imagine you want to write an email. The first step is to get whatever information you need and insert it straight into your draft. Don't worry about the potential issues with grammar, spelling, formatting or anything else. Just write it down. This point is crucial because it reduces all barriers and helps to start to write.

In the majority of the cases, developers will just stop here, especially when it comes to the emails. They just write it down and click "Send".   As a result, later on they wonder, why they get a poor responses or outcomes of this email, or they need to do a follow-up email with clarification to the previous email.

It's absolutely great that you made to this point and you wrote everything that you wanted in your draft. Next step is to revise what you wrote, before sending or proceeding any further.

Revise it

Think of this step as a refactoring. You need to refactor what you just wrote down. It can be difficult, and it will be hard to even remember to do this at first.

Revising is the act of reading what you've written and re-writing some of it to make it easier to read.

This is a list of a few general guidelines I try to follow:

• Instead of using demonstratives "this" and "that" or pronouns like "it" or "they", use the specific names of the things, even if it seems slightly redundant. It's especially good for the case when you are focused on technical writing which often requires referring to many different things at once, which may confuse the reader.
• Name objects, concepts, and procedures as specifically as you can.
• Avoid acronyms, shorthand, or jargon unless you are absolutely sure that readers will understand it.
• Organise thoughts into paragraphs.
• Write as if the reader doesn't have much time to read. The first sentence should tell them exactly what you want them to do, or what want them to know.
• If you are not sure about something you just wrote, worth to ask a friend of yours for a feedback. This is what I usually do when I finish with writing a new blog.

Polish it

In programming, "polishing" means improving readability of code by indenting, wrapping long lines, formatting, etc. In our case, it means the appropriate use of fonts, bold-face, heading and bullet lists.

The art of typography is a deep and mystical one, but its purpose is to serve the written word, making it easier to read without altering its meaning.

This is a list of a few general guidelines I try to follow:

• Format code in a fixed-width font and/or demarcate it as such.
• Use bullet or numbered lists liberally. Good practice to convert several short paragraphs into a list.
• Create headings if the document is getting long. It helps to create stopping points between paragraphs.
• Make clickable hyperlinks. This is can save few minutes of somebody else time.
• Use Grammarly which assists in writing. It highlights all obvious mistakes you made and offers a list of suggestions for the improvement. I personally use the free version for more than 2 years and can't be more happy with it.