Effective Communication on Technical Topics

Photo by Nik MacMillan from Unsplash.

At Buffer we’ve always been interested in how to communicate in concise and clear ways. In fact, it’s been part of our company values from the beginning. Every organization values communication, and I’d submit to you that it’s doubly important for remote companies such as ourselves.

It occurred to me recently how critical, and equally difficult, it can be to talk about technical topics as an engineer. It’s hard enough to speak clearly, but adding the abstraction of software development only makes things more complicated. After reading an interesting tweet from James Hickey on becoming a senior engineer, I thought it was telling that his first point raised dealt with this very topic:

We spend a lot of time constructing elegant solutions to demanding problems by writing code, but so often when it comes time to talk about the outcome of that work, the way you might’ve done it or why it mattered – it’s easy to stumble in relaying the value of your time and effort when you’re talking to someone else.

Today, I’d love to introduce you to a real world example of this I recently experienced at Buffer, how I talked through it and some tips on how to tactfully consider the person you’re trying to explain things to.

The Technical Topic

For our example, we’ll be talking about a bug report that came in recently. The bug itself was a trivial fix, but in the spirit of gaining the most of amount of context possible here are some additional details:

Users were experiencing issues uploading videos to their posts on Buffer. After reading it over initially, here’s what we can see:

1. The report notes that it happens on iPad.
2. They can work around the issue by using drag and drop.
3. The error’s text in the user interface.

For me, I immediately knew the problem after watching the screen capture – this bug was squarely centered around uploading slow motion videos (a topic I’ve previously covered here). Let’s dive in on how I did (or would have) communicated about it very differently between five different people. For each, I’ll outline each person’s demographic, what I would more or less say to them and which parts of information I would include about the bug.

The first four people are my coworkers, the last one is my wife:

1. Andy: My immediate coworker, and the only other person who works on iOS at Buffer.
2. Joe: Also a close coworker, but his focus is on our Android app.
3. Marcus: My Engineering Manager.
4. Julia: Our liaison between the users reporting bugs and the people who fix them across all of Buffer’s platforms.
5. Jansyn: My wife! For context, she has no technical background in software development and her vocation is in nursing.

Levels of Communication

Andy

Andy is the ideal person to talk to in this scenario. He is a Senior Developer at Buffer, which means he not only has a lot of iOS development expertise but also benefits from having an enormous amount of domain knowledge around the company and product. In this case, he’ll be the easiest person to talk to. You likely will have one person similar in your situation, as developing software is very rarely a solo effort. Let’s look at how our interaction went.

What I said:

“This is likely a bug in our video import logic, specifically where we create a local cache of the video by getting its NSData. AVFoundation returns something different than AVURLAsset for slow motion videos, and during our latest conversion to Multiple Composers, I think I forgot to include logic to check for AVComposition which is what slow motions videos will come back as. It works with drag and drop because the system is not giving us a slow motion video, but the regular frame rate version in that case.”

Why I said it:
Andy will benefit from having the most amount of detail between each of the interactions I’ll have end up having from the folks I’ve listed. As such, explaining the raw, technical aspects of the bug is not only “okay”, it’s quite key here. Andy will be able to let me know if he’s ran into this issue before, if he has any advice or tips, some general insight and more. In fact, the fix from our talk may lead to no code changes at all (which has happened before!). If this was you, maybe the business has decided to remove support for videos within the next development cycle, the plans that can use them or whatever the case may be.

The key when talking to other developers is to not skip on the technical details, but also leave out things that might bog down the discussion.

For example, it may not be relevant to chat about a way to optimize network requests for videos here because that’s a whole different part of the video pipeline. Our issue is around importing them, and by design those flows are decoupled. What I’m getting at is it’s very easy to get into the weeds on technical topics with technical people because you’re both in your wheelhouse, but those discussions (valuable though they may be) may need to take a backseat to getting to the root of the issue.

Joe

Joe has a strong technical background, but hasn’t done a bevy of iOS development since his main priority at Buffer is our Android app. As such, he’ll be able to chat technicalities if I need to, but the main value Joe will have comes from a product standpoint. Does Android allow slow motion videos, does the web – and if they do is there any reason why our error messages may differ from platform to platform or does the experience feel disjointed in any way?

Coworkers like this are extremely valuable in providing a different take on the technical topic. They are able to digest technical jargon, even though they don’t work on your immediate platform. Sometimes a fresh pair of eyes is all you need to get past an obstacle, and talking to them often becomes a real life version of “rubber duck” debugging.

What I said:

“On iOS, the system gives us two different types for a regular video versus a slow motion video. I think we need to tighten our importing logic to support both of them. It’s tricky because Objective-C doesn’t have abstract classes, yet in this case the type I’m dealing with acts like one so it can be easy to miss when programming for it. Does Android support slow motion video?”

Why I said it:
Joe will be a great person to talk through the problem with. I can hit him with the code talk, but I’m mainly talking to him for my benefit. From our discussion, he can get a sense of why the bug is happening and provide any product-wise insight or learnings from Android he might’ve experienced in the overall Buffer pipeline.

Though it’s unlikely he’ll have insight into the resulting code fix, he’ll be able to help me think outside the box and make sure the solution I come up with is the most obvious one. Also notice that I did include a bit of platform specific talk (about the abstract classes) and ended with a question. This can lead to helpful talks about how they test or guard against similar situations, and inform me if they have encountered the same problem over on Android (i.e he might say what copy was included, any snags he hit along the way, etc.).

Marcus

Though he is now mobile’s Engineering Manager, Marcus got his start at Buffer as an iOS developer. Since he’s only a few years removed from that post, he still knows a lot about software development, has his own side projects and comprehends things I might say to a high degree technically speaking.

But what does he need to know? In this case, perhaps the severity of the bug and how easy or how hard it will be to provide a fix to our users. Since he’ll be chatting with others I normally don’t speak with outside of the mobile team, his insights from me might inform important talks to Product Mangers or other Engineering Managers across Buffer.

What I said:

“When we released Multiple Composers, this is a small tweak I forgot to check for. I thought recent versions of iOS returned slow motion videos a certain way and they don’t, but the fix is quick and easy. I’ll have that done today most likely, and in the interim we do have a workaround in place.”

Why I said it:
We’re now getting into the territory where talking about the bug is of equal benefit to both me and the other individual. Marcus will likely be looking to get a sense of the overall impact of the bug. Will it delay a release, effect other platforms or take a significant amount of work to fix? And though we don’t generally require putting a time stamp on work, since I know this bug is simple to resolve I can go ahead and let him know it’ll likely be done today. Even if it isn’t, he can expect a quick turn around time and rest easier knowing users can get around it either way.

Julia

Julia spends a lot of time talking to customers who are experiencing problems with Buffer’s platform. As such, it’s a selfless role that requires a high degree of humbleness, generosity and a nice mix of technical skills and people skills. Since she is the glue between the customers hitting bugs and the people who will fix them – she needs to know hard and fast facts both ways. From customers, she might need device information, screenshots or more as she’ll want to give us those details since it’s likely we’ll ask for them.

From us, she’s probably looking for a resolution timetable, extra insight or workarounds that help the customer’s experience get better today.

What I said:

“This one actually isn’t specific to iPad, it’ll happen on any device right now. It’s specific to slow motion videos. I can get it fixed for our next release, for now a workaround would be to use drag and drop or not use the slow motion version of the video.”

Why I said it:
Julia will probably get back to the customer in a matter of hours. The more I can equip her with actionable knowledge, the better off she will be to help them out. Notice that she is the only one where I mentioned the bit about the iPad. Since she’s investigating the bug with customers, this information could help her. I’ve also got a workaround, and while they are never replacements for genuine bug fixes – they can unblock customers and ease tensions across the board. Finally, though she can understand a lot about technical aspects, she won’t gain any extra insight from it here so it’s key to leave that out.

Jansyn

Though she is indeed my wife – she is also a heavy Buffer user! In fact, she’s (gently ?) brought several bugs to my attention during my years at Buffer. But, she has no background in software engineering. Bogging her down with technical details won’t get her or I anywhere, so with people like this it’s best to get to the heart of the issue as quickly and clearly as possible.

What I said:

“If you upload slow motion videos right now, it won’t work. You can fix it by jumping on our Testflight build, or we’ll release a fix later.”

Why I said it:
Jansyn likely just wants to know what’s wrong and when it will be fixed. As such, there’s no dancing around the heart of the issue here. But, even though this interaction has the least amount of dialog, it’s also often the hardest segment to successfully talk to when it comes to technical topics. Just as she can quickly lose me when talking about the intricacies of a diagnosis she has seen in her emergency room days as a nurse, I too can trip her up if I talk to her the same way I would talk to Andy.

To recap, here is a quick summarization each of my interactions of the bug:

You might’ve noticed that each person’s domain knowledge or familiarity of programming on iOS linearly regresses as the list goes on. The amount I communicated also regresses along with it. This is key to realize, as it likely is the number one factor to consider when beginning your communication of any technical topic you need to talk about.

It’s also helpful to note that the heart of what I communicated from person to person does have overlap, but the technicalities and iOS jargon of what I’m saying slowly peel away like layers of an onion. Finally – you’re at the core and there’s nothing left to add except what’s most key to each individual.

Totaling up my approach, here’s how I think when talking about technical topics:

• Know who you’re talking to.
• Key in on what they need to know.
• Then, you’re ready to consider what to say and then you’ll know how to say it.

Final Insights

Most outside of our industry may not realize it, but if you develop software you are just as responsible to employ effective communication skills as you are for writing quality code.

When it comes time to explain a technical topic to a non-technical person, or even your own fellow engineers, take time to gather your thoughts and possibly reconsider the tips I’ve outlined here. It’s my hope that the quality of your discourse can improve each day around these kinds of scenarios. Think of your ability to communicate like a muscle, able to grow and mature the more you work on it. Since the lexicon of software engineering is so robust, leaving out certain bits of information can be just as important as including it. The more you work on distinguishing how to talk to whom, the better you’ll become at it.

Do you have any tips on how to communicate technical topics? Feel free to reach out to me on Twitter or leave them in the comments below, and most of all – thanks for reading!