Communication Tips For Software Engineering Teams

Communication is crucial for the success of any company. Towards the realization of a goal, no matter how many resources an organization may have at hand, it’s pointless if its individuals aren’t able to coordinate with each other on the steps needed to accomplish said goal. This is quite evident for software engineering teams.

Communication skills aren’t superpowers - they can be acquired. We at Codelitt don’t have superpowers, but we do have experiences that we would like to share.

Its importance in software engineering teams

Truth be told, proper communication is an important skill to have in any department, not just limited to Engineering. But it’s here in Engineering that we can see the full-scale ramifications of this skill.

It’s quite common for large, multi-faceted applications to require multiple engineers working on and delivering multiple features at the same time. The complexity of this increases further when you take into account front-end and back-end teams working parallel one another.

Let’s imagine a simple situation. There’s an application that’s receiving a list of messages from an API. One of our front-end engineers just finished creating a functionality that updates a message’s visualized status - using its unique id - through a button’s onClick event. Through this event a PATCH request is made to the /messages/:id endpoint. This way, we can simply change the message object’s visualized value from false to true.

The back-end team assures this is the correct endpoint. This functionality was properly tested by the Quality Assurance team and verified by the client, once it makes its way to a production deployment. So far so good.

Now let’s fast-forward a week. There has been a request by the client to include a new feature on the front-end: the ability to mark multiple messages as read. To achieve this objective, the back-end team needs to make a change in the previous /message/:id endpoint. They decided that the best approach would be to change the previous endpoint to /messages/unique/:id, in addition to creating a new endpoint: /messages/mark-all-read.

The objective here is to have two separate endpoints on the backend that will manage a given number of messages to be changed through a single PATCH request for each batch of changes (a single message or a list of messages). Additionally, the endpoints have been named in a way that is self-descriptive.

The back-end team has tested out the endpoints by making mock requests. They’ve opened a pull request to have the solution reviewed by their fellow back-end engineers. The solution has been approved.

Now comes the issue: the front-end team wasn’t informed. A major change has occurred that will impact a key functionality in the messages feature and the front-end has no idea about it. This means that from the front-end side, the feature to mark a single message as visualized is broken. After all, from the front-end, the PATCH request is still pointing to /messages/:id.

Now you can argue that the Quality Assurance team will surely pick up this break in the application. You can also argue that there will be a story card in the project’s methodology that surely won’t go unnoticed by both development teams. Perhaps you will even argue that the Project Manager and the Engineering Leads will surely keep an eye out for the sensitive features of the application.

The problem with these lines of thoughts is that they’re presumptions.

Presumption is the enemy of excellence

Never presume! Mind-readers exist only in the realm of fiction. An engineer shouldn’t have to make presumptions into a feature from a story item’s vague acceptance criteria. That same shouldn't be needed from an engineer simply having access to the Design Team’s wireframe.

In the previous story, because the back-end team didn’t notify the front-end team, a potential breaking bug could have been introduced into the application. We should also consider the possibility of the bug being sent to production through further human error. It becomes an even more difficult situation as an immediate hotfix release would be needed to address the issue in the live application.

Even if the Quality Assurance team or the Engineering Leads picked up on the issue beforehand, a significant amount of time would have been spent on identifying the issue and going through the proper protocols: creating a bug item; assigning an engineer to work on it; investigate the issue and provide the solution. Inevitably, the engineer assigned to investigate the issue would have to confirm with the back-end team and discover the difference in endpoints. All of this time spent could have been prevented by a healthy and friendly mention to the front-end team.

However, it’s important to understand that communication parallels responsibility. Just as it’s important to keep your team informed, you have to also keep each other, as team-members, accountable to one another for the health of the project.

You have to inform your team of any changes that will impact the project, specifically if those changes are overarching and unnoticeable at first glance. You have to make sure you understand the flow of a feature from all perspectives, including your colleague’s. You have to make sure that a story item’s acceptance criteria is descriptive and aligns with the client’s expectation. Too much is riding on a project to be left to chance.

How does Codelitt communicate?

Information gathering is essential in the accomplishment of any goal. You need to know as much as you can when planning objectives - there are just too many variables to risk when approaching something blindly.

One of Codelitt’s core company values is open collaboration and transparency. No matter the significance of a task, there is always a discussion made towards it.

What seems like a minor visual detail for a software engineer can have grave repercussions from the perspective of a UI designer. Nobody knows everything about everything, and that’s okay! We have intelligent people onboard who know their craft well. We take advantage of our team’s diverse skill set from the very first step: planning.

We also have an in-depth blogpost covering how Codelitt operates as a remote-based structure and tools it uses for communication, which you can check out here.

What improvements can be made?

What if the current state of communication in your team is lacking? Below we set aside the following improvements that can be made:

• Plan a meeting and reinforce the importance of communication;
• When collaborating, notify your teammates on what can be done and how it can be done;
• When a plan is in motion, notify your teammates on your current activity;
• If something doesn’t go according to the initial plan, notify your team as soon as possible;
• Be acceptant of feedback and critiques

Acknowledging a problem is the first step to solving it. In order to address the issue, your team has to know, in the first place, what effects are born from a lack of communication. Everybody has to be on the same page.

Thus we have the true baby step: actually communicating. Unless you actually say something, nobody will know your voice. A business cannot operate in silence and teammates cannot coordinate with each other under the same condition. Don’t be afraid to voice your opinion and confirm something.

“Is this possible?” Yes. “Can it be done with the current resources at hand?” Yes. “How can it be done?” Explain it. It doesn’t have to be a lecture; make it short and sweet. If further elaboration is needed, then by all means provide it.

It’s perfectly fine to give your teammates a fresh and friendly reminder of your current task in company channels. Not only does it generate a historical reference, it also sets the pace for the entire project. Your teammates will feel more relaxed knowing something is being accomplished outside of their scope and focus their attention on another task. In addition, if anything is off about your current step, one of your teammates will step in to make sure you’re on the right track.

Make no misconception, communication is a skill. Skills are developed through discipline and diligence. You may not always convey in the best way possible your idea or argument. Successful operatives have to train themselves to look at the acknowledgement of an error or failure to communicate as a learning experience.

This means exactly as it sounds: learning from it and owning it. Ask yourself: What could I have done better? Did he/she truly understand what I covered? How should I avoid this situation from happening again? It’s not about beating yourself up. It’s about recognizing limitations and working towards surpassing them.

And then there’s the nature of failures. Even company executives and mid-level managers are capable of making mistakes. Nobody is infallible, and none should be above being approached about making adjustments or taking considerations. From the highest levels to the lowest, it’s important to recognize that we’re all capable of making mistakes or having our plans suffer setbacks. This possibility shouldn’t be viewed as a problem. That being said, keeping these shortcomings silent is a problem.

Additionally, you may even find yourself blocked from proceeding with a task. It’s imperative to have a feeling of comfort towards asking your peers for input. The greatest resource available in an organization is the cumulative knowledge of its workforce.

These are simple instructions, and that’s how it should be: simple. To quote Jocko Winnick, in his book Extreme Ownership How U.S. Navy SEALs Lead and Win: “Simplifying as much as possible is crucial to success. When plans and orders are too complicated, people may not understand them”.