Communication in Engineering, Software, and Open-source

27 September 2011

Engineers and developers are not known for being the best communicators. Technical details? No problem. Explaining things in plain English? Err, that's a different story. I've seen entire projects flounder from ineffective communication through my career as an engineer.

Since transitioning to the role of startup founder and open-source developer, communication has become an even larger part of my day. Below is an analysis, including my humble suggestions, for improving the state of your projects by improving your team's ability to communicate.

A special thanks to Cory Flanigan (@seeflanigan), who gave a talk at Great Lakes Ruby Bash 2011 entitled, Communicating Effectively for Fun and Profit, which prompted me to write this, and also for providing feedback on this article.

Communication is about winning. Whenever you engage someone in communication, it is a competition. Who has the better story? Who can talk/write more? Who has the better code? And if you don't win, you lose.


Fact: if you win a conversation, then you also lose. This is especially true when your conversation must accomplish some achievable goal.

Actionable discussion

Let's first define "actionable conversation" as that in which we are trying to achieve some explicit goal, whether to persuade someone of something or to find a solution to some problem.

Now, let's divide actionable conversation topics as one of two types:

Opinion vs opinion

The majority of the time, there is no right or wrong, only opinion and differing opinion. To consider yourself right here is to disregard the differing opinion as decidedly wrong. Be careful, doing this makes it difficult to ever grow and learn.

Fact (true vs false)

Then there are topics for which there is a right and wrong. Let's say you and I are arguing the solution to 1 + 1 = 2. You say it's 2, but I say it's 3. In a technical sense, you are right and I am wrong.

In the context of communication, though, what is the point of being right if you can't convince others, or help them to arrive at the correct conclusion with you? If you are arguing with me, then you've already deemed it worthwhile to convince me. Therefore, our conversation is not about being right, it's about convincing me that you're right. And in this regard, you may be right and still be wrong.

Furthermore, true/false is a zero-sum game; if you win, then I must have lost. And if I lost, then I must not be on the winning side with you. And if I'm not on the winning side with you, then you must not have thoroughly convinced me. Which means, in the context of the conversation at hand, you still lost.

This doesn't even address the effect "winning" has on your ability to engage me in future conversations.

The only way to actually win a conversation is to make sure we both win.

When arguing fact against someone's disregard for fact, the best thing you can do is this:

  1. Present your facts
  2. Listen to mine
  3. Acknowledge the validity of my side (even if I'm wrong, there must be some convincing reasoning behind it for me to disregard your facts)
  4. Leave it alone. This is called, picking your battles.

In other words, pick your battles.

The only winning conversation is the conversation in which everyone wins. In a game of Ego, the only winning move is not to play.


When trying to affect change, we often need to convince someone to help. There are entire books on the art of persuasion [1], so I won't delve deeply into the subject here. I will instead share one lesson I've learned the hard way: Once a person becomes defensive, the conversation is over.

Human intelligence is an interesting thing. We tell ourselves that we employ logic to arrive at conclusions. More often though, we use emotion to arrive at conclusions, and then we mold logic to justify them. Sometimes it's astounding how malleable logic can be. Once someone becomes emotionally attached to their idea, logic becomes irrelevant [2].

The lesson here is to avoid turning any conversation into an issue of right and wrong, because then it is a competition. Competition evokes emotion and entrenches people in opposition. Instead, consider every conversation as an opportunity for everyone involved to grow, learn, and develop together.

Communication and software / engineering

Bringing these concepts back around to software and engineering, every conversation should be viewed as an opportunity to increase the project's reliability and applicability. If you can increase everyone's understanding of the project, consider the dialogue a success. This is a subtle departure from the norm, where conversations are started to fix a project that is broken in some regard, or to explain why the other person is doing it wrong.

For example, don't submit a bug report with the mindset that "this code is bad, causing this bug in this situation." Instead, think, "here's an opportunity to make this code applicable for this situation." This simple change of perspective will come through in your communication and make it much easier for the recipient to react in a positive way.

Communicating with engineers

Enough of the mental voodoo; how do we actually communicate with other engineers?

Engineers and software developers tend to view ambiguity and verbosity as fluff that weakens the point and hurts credibility; we tend to be succinct. However, succinctness and efficiency can easily be perceived as assertiveness and aggressiveness, which can trigger defensiveness and effectively kill the conversation.

In the real world, to prevent others from becoming defensive, we soften our stance with "I think that...", or "I feel that...", and use other qualifying terms like, "maybe" or "perhaps". In the engineering and programming worlds, these can be downright annoying, especially in written form. So we must walk this line. We must learn to understand our situation, audience, and goal; tailoring our message accordingly.

Communication in open-source

Communication can be a barrier to progress from the perspectives of both the user and the maintainer of open-source software.

When submitting patches or bug reports (as a user)

When submitting a patch or bug report, realize that the project is someone's creation, the product of their time, work, and care. It's their baby. Their reward comes from others who use and benefit from their work (and the recognition that comes with it). Avoid telling them their baby is ugly.

Make it clear that you see this as an opportunity to improve their project. Avoid making demands which convey entitlement (e.g. "this is a serious bug that needs to be fixed now"). At the same time, don't powder your prose with disingenuous praise or flattery; this is tomfoolery, and engineers are sensitive to that. (We tend to be easily annoyed).

When responding to patches or bug reports (as a maintainer)

More importantly, to open-source authors: realize that the worst thing we can do is discourage people from submitting patches or starting and engaging in conversations about our projects.

We often receive bug reports where our first response is, "You're doing it wrong." This is discouraging to the submitter and potentially embarrassing. One technique I use in this situation is to assume that I've misunderstood the problem. In these situations, I start with some form of, "I don't think I understand the issue you're having," which leads into, "Could this be accomplished this other way instead?..."

Often this yields one of two outcomes:

  1. They read through my alternative solution and realize it does work. I usually get some response like, "Oh, you're right, I get it now, thank you!"
  2. Or they explain why my solution won't work. Now I understand their problem better, and can either pull in their code or start working on a solution.

In either scenario, we've both won. In the first scenario, I've helped them to grow and learn without embarrassment (a necessary part of a conducive learning environment). In the second scenario, I've learned the true nature of their problem by working with them, rather than assuming they were wrong and then having to backtrack -- embarrassing myself in the process.

In either case, I try to conclude by making it clear that their time and efforts are appreciated. Even if they were wrong, the fact is that some level of reasoning brought them to that conclusion. Chances are, others are on the same path. Also, they will now be able to apply the sort of reasoning you gave to their next issue.

Open-source authors, remember that people who submit patches to your projects are not saying that you're wrong or incompetent. If they believed that, they wouldn't use your project. You have the upper hand in this situation, so it is ultimately your responsibility to ease the tension.

Give every ticket the benefit of the doubt. Instead of immediately concluding that the other person is doing it wrong, assume you don't completely understand what they're trying to accomplish. This is an opportunity for everyone who sees the project, to grow.

Pulling in user-submitted patches

One last thing while I'm on the subject. If someone submits a patch that comes close to something you'd want in your open-source project, pull it in!

I've seen the following situation happen too often:

  1. Someone submits a patch (or pull-request) for some open-source project.
  2. One of the project's maintainers asks a couple questions about the patch.
  3. The maintainer doesn't like some aspect of the submitter's code, so they implement the solution themselves and then close the submitter's ticket.

I think one of the reasons this happens is that the maintainer has been on the other side of the fence (being the maintainer of a successful project), for so long, having responded to hundreds or thousands of questions, comments, and commits project. They've forgotten how rewarding it is for other developers to see just one of their patches or ideas incorporated.

The next time you find yourself about to do this, I propose a different approach. If their code requires numerous changes, politely ask them to make those changes, and resubmit the patch. To really encourage collaboration, provide them with some guidance or encourage them to further improve their solution.

Protip: On Github, they don't even need to submit a new pull request. They can make the necessary change(s), amend their last commit (`git commit --amend`) and then force push to their branch (`git push -f myrepo fixbranch`). The existing pull request will be magically updated.

If only minor changes are needed, such that it's not worth the effort of asking them to make said changes:

  1. merge in the submitter's patch
  2. make any necessary changes in a new commit
  3. push both commits to the public repo at once

If they submitted a patch, it shows they have invested the time and effort to fork your project, figure out your code, research and solve the issue, then make and test their changes. To see their work re-implemented and pulled into the codebase without recognition or thanks is demoralizing, if not altogether insulting.

I won't say I'm guilt-free of committing such atrocities myself. When I have made this sort of mistake, I've tried to make it abundantly clear why. I did this by assuring the submitter their work was appreciated and encouraging them to continue submitting patches and bug reports in the future.


Effective interpersonal communication can be difficult, but learning actionable techniques helps overcome common barriers that prevent progress and growth in open-source, software, engineering, and the world. Above all else, cultivate the habit to recognize how your communication is perceived by your audience in order to increase reception and make your message more effective. Likewise, learn to recognize when your own emotions are preventing you from being receptive to new ideas and possibilities.

TL;DR (too long; didn't read)

About the author:

Steve Schwartz // Owner of Alfa Jango, CTO of Genomenon, co-founder of Carcode (acquired by in 2014), engineer, developer, open-source enthusiast, guitarist, and racecar driverist.

Comments are loading...

We're Hiring!