Be a better technical communicator

This is mostly a reminder to myself, but I know I’m not the only one that suffers from this. Partially due to my non-technical education, but mostly due to lack of attention, I often find myself frustrated while trying to explain an idea or a problem to a co-worker. It either takes me way too long or feels way too clumsy in the first place, or requires iteration, repetition, and drawing things in the air. And I have some smart coworkers.

Be a better communicator

A lot of the concepts discussed are generic; this post is merely an application to a familiar domain. The principles were taught to me (and since gradually forgotten) in debate and speech classes in highschool many moons ago.

Own the vocabulary

There is a widespread epidemic of overstatement and term misuse in the industry. I won’t call anybody out specifically, but the themes will be familiar.

What is “scale”? Which direction are you scaling?

What is “fast”? Are you talking about throughput or latency? (Unsure you understand the difference? Shut the fuck up, Donny, you’re out of your element.)

What did you measure, in what units, over what time?

Your quotidien interactions with colleagues will be much improved by a more faithful diction as well. If you’re a database engineer, learn the terms. I was guilty of this for a long time while working on indexing at SimpleGeo, and still am to some extent. Stand in your interlocutor’s shoes: it’s like listening to your parents explain a computer problem, or a person that knows nothing about cars explain a mechanical issue they’re “hearing” or “feeling.” If you don’t know that the Cs in CAP and ACID stand for, no time like yesterday to find out.

The above is especially true of high-pressure situations. Systems don’t “freak out” or “shit themselves.” If you find yourself personifying a deterministic system frequently, you should do the due diligence of understanding the events or abstain from commenting during an outage – you’re only going to frustrate the folks involved.

Which brings us to…

Know your audience

Just as you have to downgrade your vocabulary when explaining computers to your parents, you have to pump the breaks when dealing with someone new to the domain in question. Last week, I was trying to explain a system I was building to a co-worker. He called me out, and was right to do so: within seconds, I used cursor pagination, predicate tree, merge join, transform, conjunctive operator, and the list went on. No term in and of itself was unfamiliar to him, but he had just spent 4 years at Flickr, working on much higher-level stuff. To top it off, I later I realized I wasn’t using “predicate tree” in a widely-understood way. Womp!

By that same token, you may reach (and I have reached) a point where you have to read academic papers while researching problems. Many will have the feeling of being useful that you will initially be unable to confirm or dispel due to the frustrating onslaught of jargon. Your choices are simple: give up and hack something together, or learn the argot and join the intended audience. If you choose the latter, you will be able to turn the aforementioned feeling into certainty. It’s a time-consuming endeavor that is not often easily justified.


Most importantly, just take your time. If the formulation feels wrong in your head, just pause and think about it. A technical discussion is easily derailed by an incorrect word choice; attention and credibility is lost quickly and difficult to regain. You were encouraged to favor a pause over saying “um” back in school – nothing’s changed.

Be direct and explicit

All of the above will help you reduce your signal-to-noise ratio, improving your odds of being understood and listened to. To get an idea of the effect of delivery, consult the plethora of literature on the role of cultural differences in aviation accidents. Some examples are referneced here.

Leave a Reply