Writing well is essential. Try your best to get good at it

I’ve worked hard on my writing style, and continually reap the benefits of having done so. Email and instant messages take more work than face-to-face communication, and being able to convey a point clearly and concisely is an essential skill. Writing documentation is even harder, but just as important. I’ve had to navigate poorly documented code in the past, and try my best to ensure no-one has the same experience when trying to decipher code I’ve written.

I’m not saying that I’m a good writer - I’ve got a long long way to go on that front. But over the last few years I’ve definitely improved, and I can quantify that improvement by looking at the decrease in communication-based foul-ups at work.

In the past my communications with clients would often be misinterpreted. I can attribute some of the blame to fact that clients are often fundamentally uninterested in the minutiae of the product they’ve commissioned. Busy CEOs probably don’t need to understand the nuances of browser caching^[1], but they do need to know how to be sure they’re looking at the correct version of their website. Explaining technical details to people untrained in the technology is a fundamentally hard problem.

There’s no escaping email. The people I need to talk to are busy, and I’m a socially awkward developer who’ll do anything to dodge actually picking up a phone. But I do need to teach the client to use the new features we’ve built for them, and they need to make me understand the problem they’re really having (rather than just the symptom they’re able to see and describe).

Professional communication is a non-trivial problem, but over the years I’ve developed a couple of coping strategies. I’ve had to master two main skills that appear to be mutually exclusive: brevity, and tactical repetition.

Keep your writing short

Everyone’s heart sinks when they open an email and are presented with an essay. The dreaded “wall of text” will put off even the most keen communicator. Particularly when explaining a fix for a particularly tricky bug, my instinct is to go deep and detailed^[2]. Learning to cut out the unnecessary details and get straight to the point took me a long time. The people I’m writing to aren’t as interested in the nuances as I am. They want to know what they need to do, and how they can do it quickly.

Tactically repeat the important points

Alongside this newfound concision, I’ve also got great mileage from learning when to tactically repeat myself. If there’s a particularly complex point to get across, the key is to say the same thing in two different ways. The scope of clients to misinterpret a set of instructions is seemingly limitless, but I’ve found they’re less likely to misinterpret two different sentences in the same way.

Tell them something once, and they’ll just live with whatever garbled interpretation hits their brain first. Tell them the same thing in two different ways, and they’ll either get it straight away (the happy path!) or at the very least notice that their interpretation is confusing. Then they’ll actually tell you they don’t understand, rather than just muddling along.

If they don’t understand but also let you know they don’t understand, that’s fine. Sometimes things need repeating or unpicking (and sometimes my explanations are simply too confusing, and I need to work harder to find the real issue at hand). If these confusions are picked up early, everyone ends up better off.

As a bonus tip, I picked up a useful phrase from the world of solicitors: “For the avoidance of doubt…”. That one comes in handy when you need to repeat something back to someone, but want them to know why you’re doing it. Soften it if you need to, but never hesitate to say “so just to make sure I’ve got this straight…” or something similar.

Using these two strategies has vastly improved my work life; the return on investment from improving my writing is far greater than from learning a new programming language. Being good at your job is, of course, essential. But a marginal gain in writing ability will give better results than a marginal gain in coding ability.

And it doesn’t just help with clients. Most work-place communication (for me) happens over Slack now (other messaging platforms are available). And let’s not forget every developer’s favourite task; creating the docs. Writing good documentation for your code saves hours and hours of developer-time in the long run. It’s not enough to ensure every method has it’s parameters written down: you have to explain how the whole system fits together. Explaining hard things is hard, but we need to do it.

People misunderstand each other all the time, and if it goes unnoticed the consequences can be time consuming, frustrating, and expensive. If I can give one piece of advice to anyone starting out in a technical field, it’s this: work on your communication skills as much as you can. Write, write, write.

---

1. Good luck if you ever have to hear a CEO pronounce “cache”. ↩︎

2. As Carl Sagan said, “if you wish to make an apple pie from scratch, you must first invent the universe.” ↩︎