Engineering, Remote Work, Strategy

Effective Engineering Communication

Remote Software Engineers: Communicate effectively to collaborate smoothly

April 27, 2021

BriteCore’s engineers are from all over the world, and we’ve operated remotely for more than seven years. We come from different backgrounds and cultures. Because of our experience with working remotely among a widespread team, we know that effective engineering communication is key to delivering efficient and effective results in any remote software company.

What can go wrong?

Why is it important to train our software engineers to communicate effectively if all they need is to meet the acceptance criteria of a User Story and raise questions, if any?

From five years of experience working remotely and communicating with many different cultures I can say that A LOT can go wrong if communication isn’t crystal clear.

  • Questions could be interpreted in a different way than the author intended.
  • Statements can be perceived the wrong way, which could result in inadequate results.
  • Unclear messages waste a lot of time on making sure both parties understand what the intended message was.

Engineers can be blocked.

It’s normal to have an engineer on your team blocked on their task (within a window time frame). There are many factors that could lead to a block, so it is critical the issue is communicated well, or they will be unlikely to receive the results they would expect from the team.

Example of an unhelpful message

Hey team, I am currently blocked on item #### and can’t move forward. Any help would be appreciated.

While the message above clearly indicates the engineer is blocked, it doesn’t clearly communicate the desired need from the team; the team can’t help unless they understand what led to the blockage.

  • How did the engineer initially approach the task; what did they try?
  • What were the findings?
  • Is the issue reproducible?
  • Is the issue from misunderstanding the acceptance criteria?
  • Are there areas in the system they can’t reach or understand?

If some of the points above were addressed, the team could collaborate smoothly with the engineer and help with the blockage to resolve it. It would also reduce time spent on back-and-forth communication and result in unblocking the engineer more quickly.

Example of how it can be reworded to be more helpful

Hey team, I am currently working on item #### and so far based on the requirements/steps to reproduce, I understand that I’d need to do {explain what you’d want to do}. So I approached it by doing {say what you did, in bullet points}. But the results were a bit different. I am unable to {what are you trying to do to be unblocked}. What areas should I look at to try resolving this? What do you recommend I try? I am currently blocked by this. Any help would be appreciated.

Engineers may want to relay an update.

Most of the time, engineers work on either features or bugs for development, which may require communication to a stakeholder, including an update or statement.

Example of an unhelpful stakeholder communication

The pull request for the #### is merged.

The message above clearly indicates that the feature/bug is merged/released. However, it’s ineffective since stakeholders may not understand some of these terminologies, especially if the deployment strategy doesn’t release to production as soon as the pull request is merged.

  • Unreferenced pull request.
  • What do you mean that it’s merged, is it deployed and on production?
  • Is it on UAT?
  • When do our clients expect to use the feature or their bug resolved?


Example of how it can be reworded to be more helpful

The [pull request](pull-request-link) for item [####](feature-link) was just merged. It would be expected that the {client/beneficiary of it} would start using it at the beginning of tomorrow at 5 AM CT/PDT.

Takeaways

Engineers communicating clearly is as important as writing clean code. We should always ensure that we’re communicating effectively with our peers. Words can be interpreted differently from one person to another. We save the reader’s time when we’re as detailed as possible.

Quick tip: Let’s ask ourselves before sending a message: ”If I am the {person receiving} this message, how will I interpret it?” Most of the time, you will find some gotchas and missing data, which make the message unclear.

Related Articles

Stop Bike-Shedding, Start Automating
Avoid trivial bike-shedding in GitHub Pull Request reviews with the help of automation.
Useful Unit Tests: Why Do They Matter?
Unit tests are the foundation of every test suite, and following the property of readability can ensure those tests are useful and saving your team time and money.
Top 5 Reasons Why You Should Migrate to Pytest
Pytest allows us to write well written, well thought out and easy to extend test code.