How to Communicate Effectively as a Developer

Writing well is a superpower, software developers write a lot, but most of the writing is aimed at machines — businesses, however, consist of people, not machines.
Working remotely is putting higher demand on the quality of our writing
- We used to be able to scoot a couple of meters to chat to our co-worker about something
- We now write to them, sometimes not hearing back for hours or even days
  - When the round-trip time is measured in hours you 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.

We all write things, most of the time what we write isn’t very impactful, however it starts to matter, and matter a lot, in a professional setting. When what you write is read by your colleagues, your manager or your manager’s manager, it helps everyone if your writing is clear, concise, and empathic

Short-form writing

Major category of writing in every developer’s life is chat — Slack, Teams, Discord etc.
- Messages are written and exchanged 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.

A comparison of two Slack messages. One on the left shows a confusing message. The other on the right depicts a well thought-through message.

The left demonstrates 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 working out what is being said:
- what is “it”?
- who is “her”?
- “not working properly” how?
- what exactly does “bad time” mean?
The right makes the reader do less work at the expense of effort on the writer’s side. The writer clearly thought about how the message will read
- This is especially true in the second example as 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.

Developers also produce longer forms of writing such as notes, comments on pull requests, feedback on code reviews, proposals etc.
This writing is intended to be consumed at a slower pace, but 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.
- It may seem like an overkill. And sure, if you’re providing extensive feedback 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.
Keep an eye out for situations where the reader might disproportionally benefit from you spending 10 minutes vs 2 minutes writing a response.

First-order positive: you get your writing done quickly and can move on to the next task. It’s 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 (or even loss of business)

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, it’s about them
Second-order positive:
- Not only does a single recipient benefit from your extra effort but so does everyone else who reads your content
- Taking writing seriously at work and putting in the effort to delight the reader will, over time, compound into a massive body of quality writing that benefits everyone.
- It’s a 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.