12 Effective Writing Tips for Software Engineers

Originally posted in my personal blog

Excellent written communication skills are key to your software engineering career growth. It can help you deliver projects more successfully, create better relationships at work, grow faster as an engineer, and much more. The more senior the role, the more you're expected to communicate with other humans. This article summarizes some lessons I've learned about communicating more efficiently in the context of software development.

Scope 📒

This article is mostly about written communication for software engineers but it'll probably also be helpful for other roles working in the software development lifecycle.

What is effective communication 🤷

First, let's define what I call "ineffective communication." It's an exchange of messages which has one or many of these characteristics:

• Slow
• Frustrating
• Causes misunderstandings
• Consecutively makes people lose time and money

By contrast, for the purpose of this article, effective communication leads to fast and empathetic resolution of problems and the exchange of ideas with a minimum number of misunderstandings.

List of communication tips ✍️

Know your audience: Before you send any message, ask the following. What's their role? What knowledge do they have in the topic you're about to discuss? What timezone are they in? All of this will help guide how technical your vocabulary will be. It's very different to say, "Our server's overloaded with requests, and we're working to fix the load balancer," than saying, "We're having some issues with our servers but are working on it."

Have the key decision-makers in the conversation: If you don't, you might not receive essential feedback or need to backtrack on the decision afterward. Make sure to involve the right people but not anyone else.

Be action-oriented, and propose solutions: Avoid conversations of the type: - Hey everyone, did you see we have this problem - Yup, we have a problem - The end

Think about what follow-up questions the other person will ask: Try to answer them in advance, so the number of messages in the exchange is minimized.

Use as few words as possible: If your message is short, more people will read it, it'll avoid confusion and it'll take less time to make a decision. So, before sending your message, review it. Delete as many words as you can to keep the core message and avoid any fluf

Clearly state urgency and next steps: Say, if your question is urgent, what's the impact? Is it blocking anyone?

Enumerate questions : For multiple questions, it's easier to enumerate them so you can refer back to them and allow the other person to answer one by one.

If there's room for interpretation clarify! : Believe it or not, a lot of times, small assumptions or misunderstandings will be highly costly. If there's something with some room for interpretation or too vague, get to the details. The simplest way of doing this is to ask, "So when you say [insert original part of their message], you mean [shorter paraphrased version]?"

Know when to change to videocall (or IRL conversation) : Remember, written communication has limits. If the conversation is taking too long or you need to discuss live changes, you might be better off having a call

Think of solutions: Lead the conversation by saying "We have this problem, and I've thought about some implications, so I think we have these options enumerate options. What do you think?". Sooner or later, you'll be the person to whom people come for answers.

Be kind : You're (probably) talking to a person. Don't demand things; ask nicely. Say hi, and present yourself if you're talking to someone for the first time; you don't have to send your whole life's story, just a simple "Hey name, I'm an engineer at team investigating an issue related to invoicing, I could really use your help with the following...".

Respect people's attention: Messaging apps are built to distract people, so be mindful and don't @ everyone, don't @ after working hours.

Closing thoughts

Thanks for reading this far. I hope one or many of these tips are as helpful to you as they have been to me.
Again, communication is complex, but being a bit more thoughtful about what we write can go a long way.