May 25, 2021

Communicating with Developers

A unique communication challenge

While communication can be difficult in any work arena, communication between developers has unique challenges.

These challenges often center around the nature of the work we’re doing, resulting in asynchronous communication, and issues around how "it works on my machine".

Asynchronous communication

Communication between members of partially or completely remote development teams tends to be asynchronous. Developers communicate with each other across the globe, using a variety of platforms like slack, discord, and email. Frustrations can arise, for example, as developers try to communicate across time zones and potentially even language barriers to resolve development issues with colleagues who aren’t even awake.

“It works on my machine”

Then there is the pesky "it works on my machine" issue. When a developer creates a new feature, it doesn’t always work on a colleague’s - or worse, a customer's - device. This often occurs due to missing or incorrect environment variables such as databases credentials, or differing operating systems and/or browsers.

Trying to discover why someone else's code is not working on your machine can be tough, because you don't know how they got it to work, and what information they need about your machine to debug. Finding a solution in these scenarios requires ongoing back-and-forth communication that potentially becomes very frustrating.

The communication formula

No tool magically fixes communication challenges. Good results come when we cultivate empathy and develop processes to reduce friction. For good developer communication, here’s a simple formula:

  • Assume the best about the other person
  • First understand, then be understood
  • Show your work

Assume the best about the other person

Most people are just trying to do their best and developers really want their code to work for others. Yet it can be easy to become angry when you assume, for example, that another developer is being intentionally vague when your attempt to communicate with them to fix a problem isn’t working.

When communication is difficult, it’s best to take a step back and give the other person the benefit of the doubt. Ask yourself if it is possible that you’re the one not communicating clearly? Perhaps you can fix something too. In any event, choose to believe that others are doing their best to communicate effectively with you.

First understand, then be understood

When reviewing another developer’s work or trying to run their program, ask yourself these questions:

Did you read their instructions carefully? Did you follow each step? Did they leave any comments in their code, or anywhere else that might be useful?

In the best case scenario, you can solve the communication on your own by making sure you've understood and tried the other developer’s instructions. Alternatively, you may still have issues, but your next conversation with the developer builds on what you discovered on your own. When you do everything you can to understand, you show the other developer that you're not being lazy or difficult, but are working towards clear communication.

Show your work

If you are sharing your development work, have you written your steps out? Do you have an updated README? Have you added comments to your code/PR?

If you're reviewing someone’s code, have a question, or have spotted a bug, have you explained the steps it took to produce the issues you see? Can you share a screenshot or recording?

There are tools and processes you can use to show your work, and make it easier to communicate with other developers. As a best practice to enhance communication efforts between developers, your team or company should acquire the appropriate tool and write down a process to help developers show their work. For example, if your company uses BugReplay, you can capture screenshots coupled with console and network logs to show your outcomes to another developer.

Apply the communication formula

Let’s walk through a couple of “It works on my machine” communication scenarios, where two developers learn to use the formula above to communicate clearly and effectively with each other.

Example 1: Testing Authentication Workflow

In this scenario, Sally is a developer working on the authentication workflow for a new website, where users are authenticated via their Google accounts. She’s asked Bill to review her work. Feel free to check out the source code, or take a look at the live demo.

Sally just completed programming the ability to authenticate users with their Google accounts. She asks Bill to pull her code base and test whether he can log in. She sends him a link to the repository, provides the environment variables he needs to put in his .env file, and tells him the instructions are in the README.md file.

Bill clones Sally’s repo, installs all the packages, and sets up the variables correctly, but once he clicks the "Continue with Google" button, something goes wrong! He's not sure why things aren't working – he checks his .env file to make sure the setup is correct, then runs through the installation steps again.

He still gets the same error. Bill figures the best way to share what seems like a bug is to send Sally a screencast of the issue. You can see for yourself his recording in BugReplay, which captures helpful network logs and other information about the environment in which the failure occurred.

When she reviews the logs, Sally sees that Bill ran the code on the port https://localhost:8000. However, the Google authentication is set up so that it redirects to https://localhost:3000. When she contacts Bill to ask why he ran the code on port 8000, he tells her he was told to do so in a previous project, and assumed he should do so again.

Sally explains that Google requires allowed domains to be explicitly set up, and the developer domain they are using is https://localhost:3000. Bill reruns the installation, this time without overriding the default port 3000, and it works like a charm! Sally updates the README to make the domain requirement more explicit so others won’t experience Bill’s issue.

Now let’s review how Sally and Bill applied the communication formula to their situation:

  • Assume the best about the other person
    We don't know what went on in Bill or Sally's minds during this whole exchange, but they both acted respectfully in giving and receiving feedback, even when things weren't working.
  • First understand, then be understood
    Bill probably could have done a better job here. He did attempt to run through the setup several times, but when it came to starting the server, he added the --port 8000 command in order to run it on a different port than the default, which was an extra step Sally didn’t ask him to do. People often get used to doing something one way, and don’t realize that their actions might break things in a different project.
  • Show your work
    As soon as Bill realized he had an issue he didn't know how to resolve, he documented exactly what was happening. BugReplay made it exceptionally easy to hit record, get all the relevant information, and send it to Sally. From there, Sally quickly figured out what was going on and was able to take the feedback to improve the documentation.

In the end, this was a communication win for everyone!

Example 2:  Previewing a Deployment

In this scenario, Sally implements a new passwordless authentication method using 🪄magic🪄 links. Unlike Google authentication, magic links can be used for preview deployments.

As a result, when Sally asks Bill to test her new authentication method, he won’t have to pull all of Sally's code, install the dependencies, and run everything locally on his machine. Sally uses the platform vercel so that each pull request automatically deploys its own unique URL for every commit which anyone can view.

Sally sends Bill a link to her pull request, which directs him to this preview deployment.

Bill is happy to review Sally's work, but again runs into trouble. As before, he documents his attempt to test Sally’s authentication method and sends the recording to Sally.

In the recording, as shown in the video below, Bill repeatedly clicks the Continue with Email button, but nothing happens:

From the network logs Bill sends her, Sally sees that Bill gets a 500 HTTP response code, which indicates a problem on the server. She tests the preview link herself and gets exactly the same result.

After some additional investigation, Sally realizes that she forgot to add the necessary environment variables to production 🤦. She adds the variables and sends Bill the deployment preview again. This time Bill reviews and approves!

Sally and Bill have certainly become better at applying the communication formula, as you see here:

  • Assume the best about the other person
    Bill and Sally were both respectful towards each other. The preview deployment provides an ‘’objective source of truth”, because nothing has to be set up locally to view the new feature, and both of them can view the same site through the same link. This made it easy to verify that Bill tested the deployment correctly.  
  • First understand, then be understood
    Bill clearly understood what he was testing and correctly followed the instructions Sally provided. Sally made sure to figure out what bug Bill discovered. Sally could have done a better job verifying her own work before sending it to Bill. While she did test the magic links locally, she never checked if they worked in the preview link.
  • Show your work
    Bill was able to leverage some useful software to share a screencast and the network logs with Sally. He wasn't able to show what happened on the server, but he gave Sally enough information to direct her to the solution.

Conclusion

Just as we have to learn how to code, we also need to grow our communication skills.

Acquiring communication skills isn’t hard when we follow the communication formula to become more empathetic, aware, and diligent.

In the end, while understanding linked-lists can help you get a job, effective communication allows you to excel on the job.