Written communication tips for effective software developers

Giving the reader the choice to stop reading

Sometimes you have to send one email to lots of people with very different levels of context, knowledge, and interest.

Sometimes you just can’t decide between keeping it short to be objective or explaining in details to avoid ambiguity.

Sometimes you want to focus on communicating a short statement but want to include more information that people will use for future reference.

How to solve all these dilemmas? Give the reader a way out.

The reader should have the option to stop reading when they feel it is not for them anymore. Your job is to make it easier for them to notice when is a good time to quit reading your email.

You do that by writing your text with progressive depth. You start with the most important message that everyone reading the email should get. For example, informing that a new feature is live.

Keep it short, one or two sentences, then skip a line and start the next paragraph. The next paragraph should explain in a few lines what feature does in more detail.

Then you can add more paragraphs explaining what the original problem that feature is solving is, or how to use that feature (if there are users of your software among the recipients). You can add more context about how does it fit the company-wide strategy, and so on.

Be explicit when you are entering in optional content.

When moving into new paragraphs, make it clear who should read it and when. Include introductions like '“If you need more context…”, “More information for those who were not in the meeting…”, “Here are some details for future reference...”, etc.

Empathy: show and act on it

Empathy is necessary for good writing. You have to understand your reader's context and how they react while reading your text. If it is a sensitive topic, you have to anticipate how they will feel. If it is a complex, technical topic, you have to anticipate their doubts.

Sometimes you can to avoid that reaction. You use less aggressive words or more precise technical terms. But sometimes it is unavoidable. Your readers will be frustrated if you are informing them that they lost access to a repository due to a new company's policy. They will be confused if you are informing them that a new project will be using technology unknown to them.

The message itself will cause this reaction, not the writing, so there is nothing you can do about it, right? Wrong.

Explicit acknowledgment

Just because a reaction is inevitable, doesn't mean it can't be handled. An excellent way to show you care about your reader is to explicitly acknowledge their feelings.

Use phrases starting with "I imagine your confusion now..." or "I understand this might be frustrating...". It shows empathy for the reader and tranquilizes them while they read the entire message. Then you can address those reactions more specifically.

Of course, this tactic depends heavily on you being right when speculating on the reader's reaction. So only use it when you are sure about how they will feel.

After you show your empathy, act on it

Also, its effectiveness relies on an honest concern for your part. If there is any sign that you actually do not care about how the reader feel and you are just acknowledging it without doing anything to minimize it, it is a counter-productive technique.

After acknowledging a reaction, complete the paragraph with a message that will help the reader deal with that reaction. If they are frustrated with a decision, explain to them the legitimate, logical reasons that led to that decision. If they are feeling confused with technical terms, point them to documentation that will educate them on the topic.

Writing comments on internet forums

This one is hard. For starts, it depends on your intentions in the forums. I will give some tips when you are commenting in a forum with the purpose of learning, educating or debating with a genuine interest in effective communication.

It is common that we do not have this genuine interest in mind when commenting, so let me list a few occasions when that happens. Sometimes without we even notice.

  • You are angry because the other commenter seems dishonest, manipulative, rude, pretentious, arrogant, dismissive, patronizing, offensive, obnoxious, or an attention seeker.

  • You are engaging with a troll that actually is all of the above.

  • You are so right about what you are saying that you are just basically typing a lecture, not trying to communicate with someone.

  • You are more interest in having fun and getting upvotes than in what the other commenters are bothering to write.

When you are not in any of those situations, then you can focus on writing better comments.

It is both about the typing and the mindset

Skip lines to separate ideas. Just like on emails, all paragraphs need white-space between them to be perceived as such and guide the reading.

Provide context, specifically about yourself. In the anonymity of forums, it is hard to understand the perspective of the person who is communicating. Try to present the dimensions of your person that are relevant to that discussion. Avoid name-dropping and boasting credentials with the goal of impressing people reading it, but mention if a credential is relevant. You can keep your anonymity and still provide a good picture of who you are to other commenters who then can exercise their empathy.

Try to answer all questions and address all topics another commenter might have. A conversion easily becomes unsatisfying when commenters are focusing just on a particular aspect of a subject — usually, the one that better suits their positions — and ignore all other dimensions that other commenters are talking about.

Even if it is a debate, think about all the other people reading that conversation that are not actively part of it at the time. Communication in forums is always one-to-many, even if it is a direct reply on a forgotten thread.

Respect all policies and etiquette of that forum. If you are not sure what they are, go try to find them before you start commenting more frequently. Forums are social groups with social norms. If you can't respect even that, it is unlikely that you will respect its members — and that they will respect you. That said, honest mistakes happen. Say sorry and change your behavior accordingly.

Never assume with certainty, from the beginning, that another commenter is plain wrong. Even if you are talking about laws of physics, it might be possible that they are coming from another assumption or talking tangentially about other topics, and what made they look just plain wrong is actually just a failure of communication. Try to clarify the point to confirm their position.

That leads to the more broad Principle of Charity. Assume coherent, rational, and strong interpretations of what commenters are saying. They will quickly prove you wrong if they are not that coherent anyway.

Do some research if it is a complex topic or to support (or change!) your opinion. Comments are not real-life politicians debates when the only thing that matter is what you can come up with in the heat of the moment. On the contrary, these are not words in the wind; they are written words that will be registered. Do some research and fact-checking related to the topics as a benefit for you, the ones you are debating at the time, and the others who will read it all later. You might learn something and change your opinion by yourself, or might do a better job educating people on a topic that you know well. Win-win.

It is ok to say things you are not sure about, as long you are transparent about it. If you do not have the time for research or couldn't find that specific article you read a long time ago, it is ok to give your opinion anyway. If yourself has doubts, make it is explicit that it is an "impression", your "intuition" or just a "first thought". Anecdotes are fine too, as long as you don't pretend it's big data from legitimate studies.

Otherwise, all tips for effective written communication suit well for forum comments, despite its bad reputation. If you find the right forum, it is a great practice to test and practice your written communication skills.

Care and feedback

Good writing is easy to learn. You already practice every day, which is a significant first step to get better at it. But it is not sufficient. There are two things that you have to get right to improve your writing skills

  • You have to care

  • You have to learn how to recognize feedback

Do you care?

You should be consciously thinking about improving your writing every time you write. It is easy to go on automatic mode, write it all and hit send. You are usually thinking about the issue at hand, not about some meta-awareness of the communication itself. This meta-awareness is not instinctive, but it is necessary.

Keep asking yourself: am I doing a good job with this writing? You can leave all changes to later, editing it after you wrote the first draft. But the caring about the writing itself should always be there.

Do you know when it is bad?

Feedback from your writing is not an easy thing to get. One problem is that you rarely get it at all. Writing is inherently asynchronous, so when people are thinking about your writing, you are not there. And when you do get some feedback for your written communication skills, it is often mixed with feedback about the ideas that your text contained. Feedback for your writing is a very elusive thing. You have to learn how to capture it.

A reliable sign that your writing should be improved is when people are misunderstanding you. Whenever you feel tempted to write "As mentioned in my last email..." consider it as a failure on your side to communicate that. Sure, communication has two sides, and it might be the other side's fault this time. But it is much more productive to be always assuming that the fault is in your side and you could have written it better.

Also, observe when people reply with doubts about what you just wrote. Ask yourself if there was a way for that point to be clarified in the original text, leaving no room for doubts. Again, it is more useful to consider that everyone is intelligent and you could have written it better, than assuming everyone is dumb for not understanding what you just wrote so clearly.

Let your future self evaluate your writing. Now and then, read something you wrote a long time ago. Months or even years ago. You will probably have forgotten the context and all the details of the message you wanted to pass, and have some distance to judge the writing. Do it, check if the message is clear, pay attention if you are having doubts about the message. If you feel it could be better, rewrite it at the spot. It is a great exercise.

Why don't you do it now? Go find an email from more than a year ago. Look for a longer one, with a few paragraphs. Read it, judge it and rewrite it.

Communicating in technical terms with non-technical people

Make yourself clearer, not dumber

Writing in technical terms to non-technical people is an important skill to practice. It is not easy though, that's why people resort to workarounds as dumbing down content or abusing of metaphors — or even refraining from sharing the information altogether.

I believe it's better for everyone if a software developer uses proper technical terms when communicating with non-technical people in a way they can understand it. People learn something new, there is less room for misunderstandings, and it makes future communication much easier once they learned it.

So, how to communicate effectively using technical terms?

Consider this sample sentence as part of an email to other departments that do not know what a CDN or an SSL certificate is. We are going to improve it step by step.

We are now using a global CDN provider, so we have an SSL-certified faster website.

From familiar to unfamiliar rule

Start a sentence and a paragraph with familiar concepts and words. Introduce the new, technical term later in the sentence or the paragraph.

In the sample sentence, the only relevant non-technical words are "faster website", so they must come first.

We now have a faster and SSL-certified website by using a global CDN provider.

Explicit rather than implicit

Don't use the technical words as they are an unimportant part of the sentence. It gives the impression that the reader should know that already, which is not what you want. You want to make it clear that you are saying something new to the reader.

In the sample sentence, the qualities "faster" and "SSL-certified" are receiving the same en passant treatment, as they were both of obvious meaning. You want to acknowledge that SSL is a technical term and give at least a small explanation about what it means — it makes the website more secure.

We now have a faster website, that is also more secure for having an SSL certificate by using a global CDN provider.

Give tips about your conclusion

Don't surprise the reader with new information. Make it clear from the beginning what you are going to say.

In the sample sentence, the conclusion is that we are using a CDN provider. It is a technical term that you want to keep at the end of the sentence, but the reader has no clue that this is the core message until they reach it. You want the reader to know what is the new thing you are communicating. It is basically an "improvement" to the website, so tell them that.

We improved the website to make it faster and more secure: we are now using a global CDN provider with an SSL certificate.

Explain new terms, but know how far you should go

Technology is a rabbit hole of knowledge. You don't know everything that happens from a user keystroke down to an integrated circuit's logic gate. You know part of the path, the non-technical person probably knows a smaller path. You want to push their knowledge further, but you can't cover all that there is to be known in one email. Choose carefully the point you want to make and the concepts you want to educate.

The sample sentence is now more organized and explaining the effects of the mentioned technologies, but the technical terms are still mysterious. A good idea is to adequately define the concepts in simple words, even if it makes the text longer. Both happen to be acronyms, so what if we expand it? CDN means Content Delivery Network. SSL means Secure Sockets Layer. The reader may have an intuition about CDN, but "sockets layer" will only add more complexity. I believe a good choice here is to expand CDN, but not SSL.

We improved the website to make it faster and more secure: we are now using a global CDN provider with an SSL certificate.

CDN is Content Delivery Network, and it is basically a network of servers around the world that we rent to deliver the content of our website. Our users will always access the servers closer to them, so the website will load faster - if compared with loading it from one single server for all over the world. The CDN provider also has an SSL certificate. SSL is a technology that encrypts the data when a computer is communicating with another. So we are minimizing the risk of a data breach when a user is accessing our web application.

Now, I made the text much longer. Is this desirable? This is basically a case-by-case choice you have to make. How much you want to educate the reader? How much you need to keep the reader focused and save their time?

It will always be a trade-off between the level of education and length of the text. I kept the first sentence untouched and separated in its own paragraph to give the reader a choice to stop reading while still getting the core message. But then added a more detailed explanation for the curious. I usually consider this a good compromise.

Loading more posts…