Writing is the most critical skill for any developer. I don’t mean only writing code (which of course is an edge case of writing), but I mean any type of writing we encounter in our daily job: tickets, emails, messages, comments, reviews, documentation and, of course, code as well.

I don’t mean writing in the sense we were taught in primary school where we were told to build nice sentences and use rich vocabulary, even when explaining a simple thing. Unfortunately, that taught many people to make their sentences more complicated and to use obscure jargon, which is exactly the opposite of the goal we face with written communication as adults - explain complex problems in a simple and approachable way. Yes, the sentences are often complicated - but still as simple as possible. Yes, we use many linking words - but in order to guide the reader. Yes, we use jargon - but we do that to distinguish the nuance between two similar things.

Unfortunately, a lot of technical writing that I see (I don’t mean formal writing like user documentation, or academic papers, but rather the day-to-day: emails, comments, discussions) falls into one of two traps:

* Too simple. Where we focus on trying to explain the problem in a simple way and we dumb it down, losing nuance and important details.

* Too complicated. Where there’s a lot of acronyms, jargon, sometimes even latin. Technically, the problem has been explained, but you need to read it two or three times to understand.

The rule here is simple (and Einstein came up with it a while back): make everything as simple as possible, but not simpler.

Of course, like any skill, to master it you need to practise. A lot. That’s one of the reasons I started this list - to work daily on sharing my ideas in a coherent, simple way. And to work on those ideas themselves, because writing IS thinking. But that’s a story for another time.

​