How to Talk to Software Engineers (and Other Technical Workers)

January 21, 2022

This post is inspired by a similar guide I wrote at my workplace on how to coordinate with the software engineering team. Most advice will apply to all software engineers, but some will only apply either to older software engineers, or anachronisms such as myself.

Introduction

Let’s imagine you work at a company that employs software engineers. Whether you yourself are a software engineer doesn’t matter. What matters is that some of your colleagues are software engineers. Imagine that, at some point, you’ve made a request to one of the engineers and the request was not followed through, or if it was, it was done poorly. It is a frustrating situation. The question is, what can you do to improve the chances that your request is followed up on?

Don’t Talk — Write!

It’s that simple.

If your question or request is in writing, it’s much more likely to get attention. No matter the language, the spoken word is just not a great medium for communicating ideas that need to be followed up on, but that’s not even the worst part of it. The worst part is that speech is ephemeral. Your utterances are present in the physical world but for mere seconds. Worse still is that your words might only stay present in the minds of your intended recipients for just a few minutes — if they were heard at all.

Note that your writing doesn’t even have to be good! So long as you pose your request in the right place, you’re much more likely to receive some kind of follow-up. That follow up might be in the form of questions asking for clarification, or it could be in the form of the engineer handing things off to someone else, it might even be promptly fixed with the only acknowledgement of the fix being that the ticket was closed.

…but be Sure to Write in the Right Place.

We arrive at the first serious obstacle to being heard.

Let’s continue the hypothetical for a moment. You’ve written your request, and pinged an engineer on Slack. If you’re lucky, you get a response within 45 seconds and the issue is promptly fixed. The more likely outcome, however, is that the engineer acknowledges your ping, and promptly forgets about your issue. Game over. Pack your bags. Go home.

What went wrong?

It’s simple, really. Slack, Teams, Discord, and even good ol' IRC are all instant messaging protocols. They are designed and consumed in such a way that the messages exchanged might as well be ephemeral. In all instant messengers, communication occurs in a handful of barely-coherent streams of thought where any incoming train will promptly be derailed by the next one, ad infinitum.

IMs are a great choice for quick questions, especially to solicit troubleshooting help when you have a problem. They should not be where you request another person to do work.

The problem with IM is that its structure mimics the worst qualities of human speech and, with the possible exception of IRC, doesn’t confer the benefits of text communication. It, too, is ephemeral. It’s easy for your messages to get lost in the shuffle, but worse still is that IM doesn’t provide you with the tools to organize messages on a detailed level. The best you might be able to hope for is to add messages to a “saved” list, but there are likely no facilities for tagging messages, and you can forget being able to export or forward them. Yet, none of these features will help you to pick up actionable signals from the deluge of noise.

The Right Place

Issue trackers attached to code repositories (GitHub, GitLab) are a nice middle ground between “friendly to engineers” and “friendly to everyone else”.

On these platforms, issue trackers are generally well-integrated into a workflow centered on code. These issue trackers usually come with a number of features that allow users to organize tickets in ways that suit their work style. With just a few clicks, engineers can see what has been assigned to them. With just a few clicks, you can see all the tickets you have opened, and look at how the work is progressing.

Better still, these features usually integrate very tightly with email. Whenever a colleague assigns me an issue or pull request in GitHub, the platform will email me all of the details of the issue and — this is the really nifty part — I can respond to the issue in an email, and my response will appear as a comment in the issue. If you report and assign an issue in this way, the receiving end will be able to file it in whichever way makes sense to them, respond in whichever way makes sense to them, and work on it in whichever way makes sense to them.

And, to my fellow engineers, you’ve got a long way to go as well. Everything I say here applies to pull requests as well. Do you want me to review your code? Assign me as a reviewer without warning. I’ll get the email, and then I’ll get to it when I have the time (usually very promptly). Ask me in Slack or worse, a Zoom meeting, and the likely result is that I will respond in the affirmative and then promptly forget all of the important details because that’s how my brain works. Deliver your request in a way I can self-organize, and self-organize I shall.

The Best Place

Email.

Specifically, emails written without any kind of special text formatting, fonts, colours, other visual styles. What you want to send is “plain text”.

Source code is written in plain text, regardless of which programming language is used. Plain text email allows a software engineer to send code, and it will be sent and displayed to the recipient verbatim. If you work on an important new feature and want feedback, you can send the changes in an e-mail as a “patch”, and the format will allow the recipient to easily either accept the change, suggest edits in a reply, or just make their own amendments to the patch before accepting. Less time is spent communicating ideas and more time is spent sharing work.

The best thing about this kind of email flow is that it flows excellently into a programming workflow, because the underlying format of code and messages is the same and they can be worked with in similar ways. Most email clients, including truly mainstream options like GMail and Outlook, can be programmed to help you sort through mail if you receive lots of it. The amount of tooling available to help you efficiently use email is unmatched and, because it’s an open standard, the potential for integration and power usage will never be outdone.

Keep it simple.

Victoria