How software engineers can improve their writing

The following post originally was published on vplata.dev, the blog of Vicente Plata, VP of Engineering, Runway Health.

The new reality of work is remote. This is particularly true in software engineering. Terminal’s State of Remote Engineering makes it more evident.

Historically, written documentation has always been important for developers. Many years ago, when I started coding for profit, internet availability in corporate data centers in Mexico was… Limited, at best. So you ended up relying on the quality of man pages, hoping that you printed and downloaded the appropriate manuals and language documentation… And leaving a clear trace of what happened in case you, or another poor soul, would find himself in your place.

This has only become more important in the remote age. Mind you, English is not my native language, but I’d like to share a few tips I wrote about writing in Spanish which, I believe, might translate to English as well.

Crafting documentation and reports is extremely important in the multidisciplinary, asynchronous and remote world that we live in. This idea that you’ll only interact with code, and people with knowledge of how to write/read code, is simply shooting yourself in the foot.

For example: chances are that you’re going to be part of multiple teams or squads, and you’ll interact with several stakeholders. So your communication will be written, not code. Thus: writing clearly and in an understandable way will directly impact the perceived value of your contributions.

Furthermore, when it comes to networking: what you write (and how you write it) will be more impactful than almost any technical contribution you can make. Grammar, punctuation, spelling, etc… Basic checks can be automated, so there’s no reason to skip them. You’re linting your own writing, so to speak. 

I’m obviously not underestimating technical contributions. But saying that “code documents itself” as an alibi for shitty writing is almost the encyclopedia definition of false dichotomy. 🤷‍♂️

So, how can you improve your writing skills? Here are some suggestions:

1. Open Source! To be precise, nearly all big projects have examples or templates for bug reporting. For example, here are freeCodecamp’s. They also have decent documentation. Check them out, get inspired and try to fill some bugs 🐞 !
2. Set a writing goal and accomplish it. It could well be a (not shitposting) tweet a day, or maybe a couple of posts a week. Just like every habit, the trick is for them to be achievable, frequent and visible. It’s ok if you feel shame: use tools at your disposal to double-check, at least at the beginning. Learning to ride a bike with training wheels doesn’t mean that you’ll always be confined to training wheels. 🚲
3. Read. I actually hesitated wether to put this, because I know a lot of people who read a lot but whose writing is, let’s say, sub-optimal. But I’m going to guess that they’d write even less if they weren’t such good readers. Just… Take it easy. Enjoy it. Analyze the rhythm, the prose, the literary figures… Feel it. 🤓
4. Practice. Adopt a growth mindset! To my knowledge, nobody has ever been born knowing how to read and write. But opportunities are basically everywhere, so it’s a skill that’s relatively easy to take up to a decent level.
5. Favor short, concise paragraphs and sentences. Make good use of that period and full stop. Generally speaking, dividing complex ideas in smaller “chunks” will make them easier to process. Also: writing ideas in short “bursts” will make the process more enjoyable for you.
6. Read again, and edit it. Say it takes you 30 seconds to fix a word… Meh, boring! But now multiply that by the number of people that will hopefully read what you’re writing X the time lost by not understanding what you attempt to communicate. Your laziness can be chaotic 🙃 ! Believe me, when you read it, it sounds funny. But… It actually isn’t.
7. Punctuation and spelling. There are several jokes about how a poorly placed comma can make your idea… Misunderstood, so to speak. Think about that extra half a second that you save when you write as if someone was chasing you. I don’t think it’s worth it.

Of course we all make mistakes. And there’s a very valid argument towards being empathetic and kind towards those who, because of insecurity, lack of confidence or laziness, don’t write correctly. Or they simply don’t write. This is particularly true in mainly social environments.

Work-wise they can be chaotic. Don’t be chaotic, my friend. Generate value and innovation, instead of grammatical headaches.

What do you think? Visit Vicente’s blog for more, or reach out via @xnt. For more, register for Terminal’s Global Engineer career summit and attend Vicente’s session, “Moving at Lightspeed: How fast-growing companies can propel your engineering career.”

Vicente Plata is the VP of Engineering at Runway Health. He is a software engineer with emphasis in leadership tasks and roles. He also enjoys being an advisor on topics related to career growth and development for individual contributors, as well as startups with distributed workforces, remote software development teams and community building.

Prior to joining Runway Health, Vicente worked at Shopify as an Engineering Lead for Shop Pay, driving features and experiments at the intersection of in-app and web experiences. Prior to that, Vicente worked as a remote Senior Lead Software Engineer at Hims & Hers, prior to the company’s IPO on the New York Stock Exchange. Vicente works in Mexico where he lives with his wife, daughters, and Luna, his pug. He also loves gardening and hiking.