Undervalued Software Engineering Skills: Writing Well

I have been coaching several experienced software engineers to further grow professionally, since transitioning to being an engineering manager. I have noticed a few skills that people often underestimate the importance of developing. Skills that add a significant boost to the impact of any developer. One of these is writing.

Most software engineers primarily focus on becoming great at writing code. And this makes perfect sense. This is an essential step to become a great engineer within a reasonably sized team.

Successful companies, however, grow continuously. Sooner or later, the software engineering team will be beyond a few dozen people, where everyone can easily talk with everyone else. People will be split across different floors. New offices in different locations will be opened. Face-to-face communication starts to be insufficient. Channels like email, chat or video calls become more important. The pace of which this growth happens varies by company: for some, it takes years. For some of the really successful companies, it happens much more rapidly.

It is with a larger organisation that writing becomes important for messages to reach a wider group of people. For software engineers, writing becomes the tool to reach, converse with and influence engineers and teams outside their immediate peers. Writing becomes essential to make thoughts, tradeoffs and decisions durable. Writing things down makes these thoughts available for a wide range of people to read. Things that should be made durable can include proposals and decisions, coding guidelines, best practices, learnings, runbooks, debugging guides, postmortems. Even code reviews.

For people to read what you write, it needs to be written well. If you grab people's attention early on, they will keep reading and they will receive the message you intended to get across. More of them will respond to it and do it without few misunderstandings on what you meant. By writing well, you can scale your ability to communicate efficiently to multiple teams, to an organisation or across the company. And the ability to communicate and influence beyond your immediate team is the essential skill for engineers growing in seniority - from senior engineer to what organizations might call lead, principle, staff or distinguished engineer.

So how can you work on becoming better at writing? Writing clearly, concisely and in a way that is easy to read? As with every skill, it's a matter of being aware of the fundamentals, practicing, getting feedback and repeating.

For the learning the fundamentals, books are a good place to start. Two books I frequently recommend engineers to start with are On Writing Well: The Classic Guide to Writing Nonfiction and The Sense of Style: The Thinking Person's Guide to Writing in the 21st Century. Here are a few more.

Being aware of the fundamentals, re-reading your own writing and ruthlessly re-editing is the next step in becoming a better writer. Putting yourself in the shoes of who you write for and asking yourself if you are grabbing their attention early is key. Challenging yourself to deliver the same message in a shorter form and re-writing your content is another. Immediate feedback from services like Grammarly and the Hemmingway App are helpful. Asking for feedback on your emails and documents from people who you have seen write well is another way to grow.

Don't take this advice just from me. Take it from others, like employee #8 and now SVP of engineering at Google, Urs Hölzle who also says that writing clearly is an important superpower for engineers.  

Engineers often underestimate the importance of writing well. Invest in this skill to scale your ability to get your message to others, becoming a more influential engineer.

Note that none of the links in this article are affiliate links or sponsored. See my ethics statement on the lack of such links.


Featured Pragmatic Engineer Jobs

The above jobs score at least 9/12 on The Pragmatic Engineer Test. Browse more senior engineer and engineering leadership roles with great engineering cultures, or add your own on The Pragmatic Engineer Job board and apply to join The Pragmatic Engineer Talent Collective.

Want to get interesting opportunities from vetted tech companies? Sign up to The Pragmatic Engineer Talent Collective and get sent great opportunities - similar to the ones below without any obligation. You can be public or anonymous, and I’ll be curating the list of companies and people.

Are you hiring senior+ engineers or engineering managers? Apply to join The Pragmatic Engineer Talent Collective to contact world-class senior and above engineers and engineering managers/directors. Get vetted drops twice a month, from software engineers - full-stack, backend, mobile, frontend, data, ML - and managers currently working at Big Tech, high-growth startups, and places with strong engineering cultures. Apply here.