20/07/2019 Undervalued Software Engineering Skills: Writing Well

Undervalued
Software
Engineering Skills:
by Gergely Orosz

Home Writing Well

About 14 MAY 2019

My Reading List
Talks I have been coaching several experienced software
 twitter engineers to further grow professionally, since
 linkedin
transitioning to being an engineering manager. I
 github
have noticed a few skills that people often
 Subscribe in a underestimate the importance of developing. Skills
reader that add a signi cant boost to the impact of any
 Subscribe via
developer. One of these is writing.
email

Most software engineers primarily focus on

becoming great at writing code. And this makes
The Pragmatic perfect sense. This is an essential step to become a
Engineer © 2019
Proudly published with great engineer within a reasonably sized team.
Ghost

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 di erent oors. New o ces in di erent
locations will be opened. Face-to-face

https://blog.pragmaticengineer.com/on-writing-well/ 1/5
20/07/2019 Undervalued Software Engineering Skills: Writing Well

communication starts to be insu cient. 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
in uence engineers and teams outside their
immediate peers. Writing becomes essential to make
thoughts, tradeo s 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
e ciently to multiple teams, to an organisation or
across the company. And the ability to communicate
and in uence beyond your immediate team is the

https://blog.pragmaticengineer.com/on-writing-well/ 2/5
20/07/2019 Undervalued Software Engineering Skills: Writing Well

essential skill for engineers growing in seniority -

from senior engineer to what organizations might
call lead, principle, sta 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 Non ction (Kindle edition)
and The Sense of Style: The Thinking Person's Guide
to Writing in the 21st Century (Kindle edition).

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 Readable 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

https://blog.pragmaticengineer.com/on-writing-well/ 3/5
20/07/2019 Undervalued Software Engineering Skills: Writing Well

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
in uential engineer.

[See also the the Hacker News discussion on this

article]

Note: As an Amazon Associate I earn a small amount

from qualifying book purchases.

Gergely Orosz Share this post

Passionate about building products  
people love and use every day.
Engineering lead at Uber. Skyscanner,
Skype & Microsoft alumni.

Amsterdam, Netherlands

Subscribe to new posts

Read more about engineering, tech
leadership and distributed systems. Get
noti ed via email when a new post is
published. Subscribe here.

https://blog.pragmaticengineer.com/on-writing-well/ 4/5
20/07/2019 Undervalued Software Engineering Skills: Writing Well

READ THIS NEXT YOU MIGHT ENJOY

Good Code Reviews, Better Code review request best

Code Reviews practices
I have been doing day to day code When an engineer proposes code
reviews for over a decade now. The changes to the codebase as part of
bene ts of code reviews… their work and have code reviews
in…

https://blog.pragmaticengineer.com/on-writing-well/ 5/5