Professional, technical communication is one of my soft spots in software development. It’s useful in situations like code review, status update, standups, meetings, backlog refinement…

Check this post if you’re looking for tips on how to improve your everyday communication.

Check out also part 1 – 10 communication quick wins for developers.

1. End your questions with a question mark

Obvious? Maybe.

Easy to implement? I think so.

Performed by the whole world? Hell no.

Unfortunately, I’m confused because of no question mark way too often. Although the confusion should usually be compensated by English grammar, not everyone uses it correctly.

Compare

Looks better

Looks better?

2. Give up on “just”

…and similar words indicating easiness – “only”, “easy”, “simply”…

These words bring an assumption that something is easy. While this may seem easy to you, people may come to your comment with different experiences. In case of for example code review, that can bring unnecessary emotions.

In other words – “just” carries opinion which you should avoid when writing technical documents.

There is the blog post which opened my eyes on the topic.

Compare

Installation: it's easy, just run bundle install

Installation: run bundle install

3. Be careful with “but”

When saying something negative (on feedback session or in code review), it’s tempting to disguise it with a friendly beginning. This usually ends up with two different-flavored sentences divided by “but”:

You are a great developer, but you argue too much.

On the surface, it may appear good, but it’s not. Typically, the other side doesn’t acknowledge the possitive beginning. Such a “but” in the middle of a sentence completely crosses out its first part.

And no, it’s not about using synonyms. Don’t replace “but” with “although”, “yet” or similar. The same apply to these words too. It’s about meaning, not the particular word.

I would advise you to completely drop “but” sentences, at least in feedback-like communication.

How to deal with it if you struggle with rephrasing it? One approach: replace a “but” with a full stop. Probably not an ideal solution, but a good start.

Compare

This is a good solution, but I would do this otherwise.

This is a good solution. I would do this otherwise.

4. Tell everybody directly

Don’t rely on indirect communication. If you have the same communicate for a bunch of people, tell all of them directly.

From time to time, people approach me with messages like: “Hey, this and that is important. Please tell X and Y”.

Inside, I’m always like: “LOL, why don’t you tell them yourself?”.

I don’t want to take responsibility for miscommunication, misunderstanding, and clarification. What’s more critical, I don’t want to spend time on all this. Such situations sometimes make me a communication hub in the whole conversation just because I was the first one approached.

Tell us all. It takes as much time.

5. Tell your motivation

It’s a nice way of sheding more light into your communicate.

If you feel that your message lacks clarity, this might be a good option. There’s no need to do that every time.

Compare

Have you recently changed something related to X?

Have you recently changed something related to X? I'm asking because I'm facing weird exceptions that I can't relate to anything I was working lately (...)

6. Use as few words as you can

You aim for removing dead code, don’t you? Similarily you should aim for removing noise words which bring little or no value to the message.

One of the ways to reduce noise is scanning the message word by word, and considering if the message is any worse without it.

Cross-tip: Typically, “just”, “only”, “basically” and similar make good candidates for noise words.

Compare

Guys can you please just see my comment that I've just added here: <link>?

Please see my comment: <link>

7. Elaborate on pronouns: “it”, “this”, “there”, “here”

They easily get ambigous or unclear.

One of the technique how to exercise the skill: try to explain a simple operation (writing a Hello World in your favorite editor?) to someone using words only. No showing, no gestures. The less technical and more malicious your partner is, the harder but better for you 🙂.

Compare

I don't like this. It repeats here many times.

I don't like the variable name. "User" prefix repeats in the class code many times.

8. Leverage paragraphs

A nice way to ease other people the reception of your message.

You could group 1-2 sentences into paragraphs so that they read it with better pace.

Another idea: after a text wall, include one sentence “too-long-didnt-read” paragraph for lazy not interested in details people.

Compare

This PR contains changes from 3 previous PR: #1, #2, #3. I don’t expect us to find any more bugs in it, as those PRs had already been checked. In case you want it, you can check this PR normally. If you want me to change something, I would need to recheck against those tasks requirements, as they were carefully validated against business people. So I would rather expect a quick approve so that #5 isn’t blocked.

This PR contains changes from 3 previous PR: #1, #2, #3.

I don’t expect us to find any more bugs in it, as those PRs had already been checked. In case you want it, you can check this PR normally. If you want me to change something, I would need to recheck against those tasks requirements, as they were carefully validated against business people.

So I would rather expect a quick approve so that #5 isn’t blocked.

TLDR: no need for a detail check. #5 is blocked on this one.

9. Aim for no communication ping-pong

Sometimes the question you ask is not open and you know what to do in each case. Try to provide the whole algorithm.

Blocking on decisions and clarifications is a typical bottleneck in software development.

Compare

– When do we make a deploy?

– When should we?

– I don’t know, normally we do them at 1AM

– Is this a typical deploy?

– It requires to run migrations beforehand, so Robert needs to be present

– Robert is on vacation

– …shit

I have to deploy a ticket with migrations. If Robert is present, I would make it at 1 AM as usual, and ask him to run them. If he’s not, I would either revert this ticket or nag PM to find another person who’s eligible to run migrations.

10. Mention people carefully

On Slack, you can @mention people. If you do it, they get notified and later highlighted, but what’s worse – it’s likely that you just interrupted with their work.

If you talk to somebody, it’s probably worth to mention them, so that they know more easily.

However, if you talk about somebody, think twice if you want to risk their focus and deep work to see a message which isn’t even for them.

A rule of thumb – don’t metion people who you talk about if they aren’t recepients.

@here and @channel mentions bring even more complications, but it’s a topic for another discussion.

Compare

@Bartek let's make a call after @Kamil is done with his final fixes

@Bartek let's make a call after Kamil is done with his final fixes