Sharpen your writing skill posted on 24 February 2024

When I was a new grad, I thought writing code was everything for a software engineer. I couldn’t be more wrong, you need so many more skills. One of them is the ability to communicate efficiently in writing.

As a junior engineer in a large company, you may see the need to write documents because your senior peers do it and/or because your engineer ladder mentions the need for a design doc to reach the next level. Having this awareness is not enough to write well though – the most obvious proof is how in large companies some junior engineers write 50 pages long design docs with code inside.

Writing is just a tool to communicate efficiently and if you want to do this well, you have to:

  • Keep your writing clear and precise – e.g. don’t write “utilize” when you mean “use”.
  • Build a clean narrative that is easy to follow – you need to capture and maintain your readers’ attention. The best way to do it is through an interesting and easy to follow story.
  • Understand your audience – your docs should be tailored for a specific audience (e.g. whoever is impacted by your proposal). There’s no need to add a dozen pages of historical context if every person who will read your doc already has this background.
  • Keep it short – as a senior IC with limited time and a specific focus (privacy/compliance), I would rather read a one crisp pager than a 50 pages long doc with unrelated fluff. Practically speaking, I read short well written docs first.

TL;DR is that writing well is hard.

As we have entered a new era of AI, tools like Chat GPT may help, but these won’t fully replace the need for this skill – you need to build the story/narrative yourself and you must be able to correct/polish Chat GPT output. This is akin to writing code with Co-Pilot – it’s a tool to boost your productivity, but you must be able to review/correct the generated code.

Last but not least, writing is an opportunity to sort your thoughts and stress test your opinions. I personally find value in crystallizing some thoughts on paper even if I won’t share them – and every now and then, I’ve realized that an idea wasn’t that great after writing about it.

Fun fact: I’ve written a lot of crisp one pagers at Databricks that are interconnected, but have yet written a 50 pages long design doc.

LinkedIn post