How to communicate effectively as a developer

Writing effectively is a superpower, there is no denying it. As a software engineer, you write a lot. Most of the writing you do is for computers. Businesses, however, consist of people.

Many of us work remotely which puts higher demands on the quality of our writing. If a few years ago we were able to scoot a couple of meters in our office chair and talk to a co-worker about something, we now usually write to them. Sometimes we won't hear back until several hours later, maybe even days. When the round-trip time is measured in hours, you'll want to consider what and how you write to avoid the gut-punching "What do you mean?" a day later.

Communicating effectively as an engineer means empathically increasing the resolution of your writing.

Short-form writing

The first major category of writing ubiquitous in every developer’s life is chat — Slack, Discord, Telegram, WhatsApp, etc. Whatever the platform may be, the messages are exchanged — written and read — quickly.

Writing messages on Slack isn’t what engineers get paid for, though. Writing code to solve problems is. Instant messaging tools are seen more as a necessary evil to get work done in a team than anything else. Because of this dynamic, there is a tendency to elide details or cut messages short, sometimes at the expense of legibility.

Let’s look at a couple of tactical examples 👇🏻

In both cases, the example on the left is what I call “low-resolution writing”. There is very little context, too much reliance on pronouns and unclear references. The writing is not empathic —the reader has to spend extra energy to work out what is being said:

• what is “it”?
• who is “her”?
• “not working properly” how?
• what exactly does “bad time” mean?

The examples on the right, on the other hand, try to make the reader do less work, even though it is more effort for the writer. The writer clearly has thought about how the message will be read.

Especially in the “team channel” example on the left, it is unclear what the writer is even trying to convey. It is a statement, do I have to acknowledge it? It is ambiguous, should I follow up with questions? Is the writer looking for help or simply quipping that there is a problem?

On the right, however, the writer has gone through the trouble of telling the reader:

• what symptom they’re seeing (assuming they pasted the exception afterwards);
• what they have tried in order to resolve the problem; and
• that they need help.

Someone familiar with the problem will be able to help immediately instead of having to start solving the mystery of what the message author meant.

Longer-form writing

The second category of writing many engineers carry out daily is producing notes of all sorts — comments on pull requests, feedback on design documents, proposals and RFCs, code comments, and so on. Usually, this type of writing is to be read “offline”, at a slower pace. The rules of high resolution and empathy apply here, too.

Longer-form writing gives you an opportunity to dive deeper into why you are saying what you are saying. It is a chance to educate, to teach, to help understand and to level up.

In the above example on the left, the comment I wrote does its job — it states that the introduced endpoint isn’t RESTful and that there is a bug in the implementation. There is nothing inherently wrong with this review comment, although it’s a little cold.

On the right is the comment I actually wrote. Because I knew the context and the recipient, I took some time to explain how the buggy implementation could crash and elaborated on how to fix it “properly” by making it more RESTful. It may seem like an overkill. And sure, if you’re providing feedback like this to an industry veteran, you are going to get some weird looks. That’s why it’s important to understand the context and write for the reader, empathically.

Now, I’m not saying you should be producing essays every time you sit down to do a PR review or provide feedback on a design document. Often it is totally fine to leave a few short, clear notes. But keep an eye out for situations where the reader might disproportionally benefit from you spending 10 minutes vs 2 minutes writing a response.

Long-form writing

This category of writing is very difficult to give tactical advice for. The length of documents produced can vary from a single page to several thousand words of prose and it's usually where structure and flow really start to matter.

Many organisations cannot afford (or simply do not see the point of) hiring a technical writer, so the task of producing clear, helpful, accurate prose falls on you, the developer. This, in turn, requires you to be your own editor.

Although this is true for shorter-form writing as well, I would recommend thinking about long-form writing, especially, as a lever. The clearer and easier-to-understand you make your writing, the longer the lever gets.

Here's a concrete example:

Imagine you run a web service. It has a bunch of users. The service is powered by an API which you decide to open up to your users so they’ll be able to build their own integrations and interact with your service programmatically.

The quality of the API documentation will carry an astronomical amount of leverage. This leverage will work in both directions.

Genuinely helpful documentation is the difference between being swamped by support requests from frustrated API users and significantly increasing the usage of your service. Happy users beget more happy users.

API docs is just one example, the same goes for other texts like specifications, design documents, and feature and project pitches.

Why writing matters

We all write things. Most of the time what we write isn’t very impactful — a reply to a random email, quick banter with friends on Discord, a birthday card to a distant relative.

It starts to matter, and matter a lot, in a professional setting. When what you write is read by your co-workers, your manager or your manager's manager, it helps everyone if your writing is clear, concise and empathic.

Low resolution, shallow writing is first-order positive, second-order negative

First-order positive — You get your writing done quickly and can move on to the next task. It is more efficient.. for you.

Second-order negative — The reader will have to spend more energy to try to figure out what you wanted to say. Depending on the audience, the outcomes may range from frustration to loss of business.

High resolution, empathic writing is first-order negative, second-order positive

First-order negative — You will have to spend more energy to make your writing easy to follow. You will have to grapple with your own confusion and holes in your understanding. You will have to figure out what the appropriate density for your writing is.

It's not about you, though.. It's about them.

Second-order positive — Not only does a single recipient benefit from your extra effort, what if ten people read your good work? A hundred? A thousand? What if the company CEO reads it? Taking writing seriously at work or in your organisation and putting in the effort to delight the reader will, over time, compound into a massive body of quality writing that benefits everyone. It is a literal win-win-win:

• your readers gain a better understanding and level up,
• your organisation benefits from better sharing of knowledge and increased productivity,
• you get better at conveying your ideas and improve your career trajectory.

Produce writing you would read with delight if you were on the other end.