I Couldn’t Describe an Apple at eBay. It Changed My Entire Career (The #1 Skill in Software)

We were split into groups of about 5 people and then asked to spend 10 minutes writing down our description of an apple that each of the groups were presented with.

I thought “This is easy.” — How wrong I was, it was a life changing moment.

As different groups started to share their descriptions it instantly dawned on me how differently everyone sees the world. Some groups — who happened to contain the most technical people — described the apple in incredible detail. Starting at the top of the stem they spent the next 3 minutes describing just the stem!

It was so different to my approach which would describe the whole apple in about 1 minute. I glanced over the stem making assumptions like “Everyone knows what an Apple Stem looks like” and “I need to describe the main body of the Apple and not spend too long doing it”.

I sat after the session with the realisation that all my prior assumptions about communicating my ideas in a group setting were seriously misaligned.

What Is Technical Communication

Press enter or click to view image in full sizeThe Anatomy of an Apple

Another pivotal moment happened not long after when I was watching Javascript — The Hard Parts on Frontend Masters — this is a course by Will Sentence and one of the main takeaways from watching this was how important your “Technical Communication” was.

He described “Technical Communication” as your ability to be able to explain and convey complex technical concepts to other people.

Let’s look at an example.

function printData(data) {
console.log('data');
}

// Assume this fetch request takes 200ms
const futureData = fetch('https://jsonplaceholder.typicode.com/todos/1');

futureData.then(printData);

How would you explain this code to a colleague (assuming they know something about Javascript and code in general)?

There are many variables to take in mind but to keep things simple I will give an example of some “Bad Technical Communication” and then some “Good Technical Communication”

Bad Technical Communication

There is a fetch request to a placeholder url which is called and then when that returns the Promise another function is called which logs out the word “data” to the console.

Good Technical Communication

There is a declaration of a function called printData which takes one argument. This argument is not used, which could be a bug and should be removed if not used. This function console.logs out the string literal ‘data’ when it is called. Next there is a declaration of a fetch request which will return a Promise and this is assigned to the const variable futureData . On the next line this futureData has a then method which registers the printData function as a callback when the Promise resolves successfully.

Both of these explanations are “correct” but one is significantly better than the other. Why?

It’s about being precise with your wording. Precision in wording and articulation is particularly important when explaining technical concepts or code because slight variances can make a massive difference.

Example:

• When the Promise returns, the function is called.

vs

• When the Promise resolves successfully, the function is called

Here, we have ‘returns’ vs ‘resolves successfully’. It may seem like an insignificant detail but it’s these key details that make all the difference. A Promise either resolves or rejects, it doesn’t return anything. If you want to get good at Technical Communication you really have to focus on these details.

Technical Communication Is Probably The Most Important Skill

I would argue that having good technical communication is probably the most important skill you can have in Software.

Sure you need to know the language/s you work in deeply, you need to know good design patterns in code, you need to be able to build out high quality scalable products — the list goes on.

But if you can’t communicate your ideas well to those people around you, then you are doomed.

Your career progression will be stalled.

The projects you get to work on will be limited.

You will struggle to make the impact you desire.

How To Improve Your Technical Communication

I will propose a couple of ways in which you can improve your technical communication.

• Writing — Even if just in private, actually writing down concepts you want to explain can really help you get your thoughts in order. This method really helps you find the details you aren’t clear about.
• Know Your Audience — Don’t get too technically orientated for non technical people and don’t skimp over the details when speaking to developers.
• Practice — Deliberate practice can be very helpful. Make a point to get into situations where you have to explain code or technical concepts. The Daily Standup can be a great place for this.
• Ask For Feedback — If you can ask a mentor. If not, ask AI.

Conclusion

One of the reasons man has become so dominant on this planet is due to our communication. We can work together and share elaborate and complex ideas. We have incredible mental capacity to hold ideas in our head and visualise and imagine things long before they exist in the world.

If you can’t convey your ideas well then your colleagues may fail to understand you and if they can’t understand you then it’s very likely your ideas and concerns won’t be taken onboard.

Therefore, if you want to succeed in software it’s important you become really good at “Technical Communication”. It’s not easy but if you want to stand out amongst your colleagues it’s vital.