Good communication in software development teams

You can read a PT-BR version of this post here

Most of the software developers spend a good part of his/her day communicating, whether with co-workers or even clients.

This communication is most of the time done by writing, which, in some cases, can result in a few misinterpretations even between good communicators.

GitHub, chats, video conferences/calls and e-mail are some of the media we use. What is sometimes forgotten is that each one has its pros, cons and specific purposes. When misused, they can generate a bunch os noise: useless conversation that can sometimes harm the focus of a developer on activities that really matter.

This post is about a few tips to improve communication between the members of a software development team, focusing on "when" to use each media to each purpose and, mainly, in a efficient way.

Chats (Slack, Hipchat, Campfire, etc)

Overall, chats are the media where most of the communication between a team occurs.

Divided in public channels (with a bunch of people) and private channels (with only two subjects), is media very likely to present noise due its intense use.

The golden rule here is simples: try to annoy as few people as possible when trying to communicate. Our work as developers demands a lot of focus and being interrupted during our thinking process can make us less productive.

Here are a few tips on how to make good use of your chat:

  • Ensure there's a good subject division per channel. Don't mix one project with another one, for example.
  • Don't mix "fun" from serious business. It's important to have a scape goat channel for flooding, gifs and such. This usually prevents serious channels to be "polluted".
  • Avoid mentioning @everyone @all the time. Most chats nowadays have a mention feature that sends a special notification for some user. This can also be used to notify ALL the members of some channel. Use this feature with caution: most of the time you don't really need to poke EVERYONE to answer you.
  • Mute (or leave) channels that don't matter. If someone has "invited" you (I mean put you there) "just because" and its subject doesn't really matter, don't waste your time and attention on it.
  • Avoid too many bots. Most chats nowadays let you add bots that send notification from other services (GitHub, for example, allows you to add bots to warn when some action happens on some repository). What on first sight sounds like an awesome thing, can soon turn to chaos if the number of posts is too frequent. Example: usually users already receive an e-mail when something happens on some repo. Now imagine receiving the same alert ALSO on your chat. This kind of thing usually bothers more than help and should be avoided.
  • If the subject is only between two people, look for a private chat. This is only a reinforcement of the "try to annoy as few people as possible when trying communicating" rule.

GitHub

If your team uses the open source software development process (with pull requests, reviews and etc) on your projects (if it doesn't, it probably should) it's pretty common to have feedback coming and going all the time.

On that, it’s important to communication to flow clear and and straight to the point (we're talking about deliverable code).

Here are some tips on how to provide good feedback on pull-requests comments:

  • Go straight to the point. You don't really need to tell a 3 paragraph story to make yourself clear.
  • Highlight what's irony and what's the real deal. The use of irony can make it difficult for the reader to understand what was really said.
  • Stick to the context of the PR. If you found something that you don't really think is working but it's not related or critical to what has been implemented on the PR, comment somewhere else.
  • Highlight what really is a blocker and what's just a suggestion. Many comments are style-related or just nitpicks and must not be a blocker to merge a PR. Making this distinction clear when commenting is a good thing.
  • If a thread goes for too long, move to a more "instantaneous" media (like chats of calls, for example). This usually solves the discussion faster.

This post has some good tips on how to express yourself during a pull-request review and it's worth a check.

E-mail

This is probably the most "pre-historical" and underestimated of the media mentioned here, but it still has its value on your workflow.

The e-mail has two very important features: it's asynchronous (usually you don't need to reply an e-mail right when you receive it) and permanent (if you don't erase an e-mail, it'll stay there forever). GitHub comments also present this two features, but they're usually hard to retrieve.

If you're going to exchange some very important information like critical decisions agreed with clients, docs or basically anything you'll need in the future, the e-mail is, among all the media mentioned here, the one with searching and retrieving tools. All email clients from today have a good and efficient search system.

Chats usually have a high flow of information exchanged all the time, that makes it harder to search anything. Meanwhile, many chat tools limit the amount of searchable and recoverable messages, which is also a problem.

Of course, using e-mail to store information would not be needed if you were a very organized person with a organized cloud storage system (Dropbox, Google Drive and others). If you're this type of person, awesome! Otherwise, let your indexed e-mail service be organized for you ;).

Video Conference (Hangouts, Skype, ScreenHero, etc)

When a conversation isn't clear enough or is taking too long, one good solution is to start a video (or just audio) call with the ones involved.

These calls are usually very consuming because they depend on a lot of attention of its participants (that usually avoid multi-tasking while on calls). This is something that must be used on small but effective doses to avoid wasting time of the ones involved.

To discuss code reviews, screen sharing is fundamental. Apps like Google Hangouts, Zoom and ScreenHero (my favourite for this job) have this feature.

This media then is very suitable for solving long discussions in a quicker and more effective way than the other ones mentioned here, making up for its cost most of the time.


TL;DR

  • Use your chat in a way to annoy as little as people as possible, always keeping the channel on topic.
  • Use GitHub for straight comments. A thread is going for too long? Move to another media.
  • Use your e-mail to save important stuff that'll surely need to retrieve later.
  • Make videocalls to clear up things that are dragging for too long on ther media.

Remember:

Good judgement is the key here and always try to put yourself in your teammates shoes. Nobody likes to be annoyed for bullshit :)


Do you have some tip or suggestion? Write a comment!