Logical Communication (for Devs)
Tags: career
Published: 2022-09-07 16:00:36

Disclaimer: This is an article about communication between developers, and it’s discussing communication in light of American culture – Your mileage may vary.

As a programmer I strive to be logical.  Logic, after all, is a key component of being a good software developer.  In good software development, there’s no room for guesses or emotional decisions – only logical decisions make good software.

Because “logical thinking” yields such good results when developing software, it makes sense to apply it in other parts of your job.  After all, it becomes almost innate after a while.  We’re programmers.  We’re always logical.  It’s just what we do.  So, communication, documentation, testing, business analysis, design and all the other aspects of the development become logic driven.  Usually, this isn’t a problem, in fact, it’s usually a benefit.

However, part of being a good software developer (unless you work entirely for yourself) is interacting with people.  Writing emails, discussing on calls, sending chat messages, or even face-to-face conversation, if you’re a developer who still goes to an office with other people in it.  (Your pet pomeranian who sits in your lap while you work at home doesn’t count.)  It can be easy to just approach job-related personal interactions like we would anything else: with logic.  This can be good, but it’s often imperfect.  Logic should be “tamed”, with two other attributes: tact and humility.

Ah, tact!  The (seemingly) unachievable, oft-ignored aspect of communication that makes decent communicators better communicators.  Let’s take a common scenario: you’ve tested your code on dev and it works great, so you move it on into the QA environment, where it’s inexplicably broken.  After half an hour of exasperation, you discover that one of the web services your code relies on is returning 500s in QA.  Well, no wonder  your changes won’t work!  Somebody else pushed broken code to QA!  You “logically” concoct an email to your unfortunate coworker: “You broke service such-and-such on QA.  I’ve tried multiple times with these parameters, and it only returns 500s.  Please push a fix ASAP.”  This isn’t unkind (we even said please!) – it’s just logical and direct.  However, there’s a funny quirk of developers that makes this kind of communication less effective than it could be: We developers tend to be very personally involved in our code.  Remember, code is logical, so, if someone criticizes our code, they’ve effectively criticized our own ability reason logically!  This can come across as something of a personal affront.

There’s really two big things to change about the message: first, take away the personal aspect.  Notice that message says “you broke service such-and-such on QA”.  That “you” is a problem.  This seems like you’re criticizing the individual, which just naturally makes us humans less receptive.  A simple statement of fact is less abrasive.  For instance, consider this version: “Service such-and-such is broken on QA.  I’ve tried multiple times with these parameters, and it only returns 500s.  Please push a fix ASAP.”  This is better, but it still comes off a bit accusatory, hence, a second revision is needed.  Let me explain.

This is where the second aspect I mentioned comes in: humility.  You think the problem is that someone else broke the such-and-such service on QA, but, in reality, as logical as we all think we are, there’s still a possibility that we got it wrong.  Humility is difficult – it’s not innate to some of us.  If it’s not, you may have to learn to fake it until you make it.  (Wait!  Don’t shut this article down because I just adapted a painfully overused cliché!)  It’s best to phrase your communications with humility, rather than an air of certainty.  This does two things: one, it makes your message a little more palatable to the receiver, and two, it saves you some embarrassment if you do turn out to be wrong.  Frankly, life’s just easier with a little humility.

Let’s try one more revision of our message, this time applying some humility:  “I’m having issues with service such-and-such on QA.  I’ve tried multiple times with these parameters, and it only returns 500s.  Do those parameters look correct to you?  Any thoughts on what the problem could be?”

This is a much less antagonistic request, and is more likely to get a fast, helpful response than our original “logical” statement.  The main thing we’ve changed is to write the message with the assumption that we could still be mistaken, and be at fault in the issue.  This required a few changes.  First, we’re removing the command at the end (“Please push a fix ASAP.”).  If the developer investigates the issue and finds out that they were the ones who broke service such-and-such, they certainly can figure out that they need to fix it.  The directive really doesn’t do anything other than put them on the defensive, which really decreases the likelihood of our getting some timely help.  Secondly, we’ve put the blame on us.  Notice: “I’m having issues…” and “Do those parameters look correct to you?”, implying, “I may have gotten the parameters wrong, which could be causing this issue”.  These lines put the blame back on to ourselves, and is just much easier to read as the recipient.  (Go ahead – try reading the original to yourself, and then the latest version we just developed.  I think you’ll see there’s a big difference in the tone, and how you feel about the message and the messenger.)

Astute readers may notice I added one more question – “Any thoughts on what the problem could be?”.   While this doesn’t directly fit into our key points of humility and tact, this is a hint to get the recipient to think about the bigger problem.  We don’t want the developer we’re messaging to see only the question “Do those parameters look correct to you?”, check the parameters, confirm they’re correct, and stop looking into it!  (After all, we’re pretty sure that the issue really is with the change they pushed to the such-and-such service, and that the parameters really are correct.)  Hopefully, this will prompt the recipient to look a little further into why the issue is occurring, and help us fix it.  This gentle nudge is still phrased as a question though – remember, you want the recipient to feel consulted, not accused.

“But wait!”, I hear you cry.  “Why can’t I just be logical, and respond to messages without all this overhead, and dancing around the issue?”.  The truth is, I believe this method of communication actually is the most logical, in that it is the quickest, most efficient way to get help from co-workers (admittedly somewhat anecdotal, but well-backed by research and the experiences of others, I think).  If communicating issues to people in the direct, “logical” way with which we began achieved the best results, it would be the most logical, but that just doesn’t seem to work with people.  At the end of the day, communication is about working with people, not computers (yes, developers are people), and people are more complex, and have varying personalities that can affect the way they perceive a message – a little tact and humility goes a long way – that is, in my humble opinion.

What are your thoughts?  Have you found purely logical messages to work the best?  What about other approaches altogether?