Working in professional software development teams requires a lot of writing. As you advance in your career, frequently the percentage of time you'll be writing emails and other correspondence versus writing source code will increase. As your responsibilities grow, so too does your need to communicate effectively with larger numbers of people in and beyond your organization. Writing effectively is a huge topic, and writing well can certainly help you in your tech career. However, in this article, I want to focus on writing efficiently.

What do I mean by writing efficiently? Writing efficiently means reducing the amount of effort you put into your writing, while achieving the same (or often better) results. Inefficient writing often results in wasted effort on the part of the writer and extra work required on the part of the reader. And busy would-be readers often won't make the necessary effort, resulting in much of your writing going unread by its intended audience. Remember, in communication the message is the message received, so you want to do your best to ensure your message is received, in its entirety, as intended.

Align Your Message With Your Medium

Today we have many different ways in which we can communicate (in writing, electronically) with one another. Some would say too many. When you have something to say, you first need to decide where to say it. Within most corporate environments, you might have some or all of these options:

• Email
• Slack/Teams/Discord etc.
• Confluence/BaseCamp etc.
• Wiki or KnowledgeBase or Docs
• SMS message
• Issue/bug tracking system or Trello/Kanban board
• Company or personal blog

Each of these has different expectations attached to them when it comes how messages are structured and, importantly, their length. We'll come back this in a moment.

Align Your Message With Your Intent

Take a brief moment to consider what your expectations are from those who read (or should read) your message. Are you seeking to inform? Are you requesting information? Are you starting a discussion? Are you requesting specific action? Each of these intentions on your part have implications on your choice of communication medium as well as how you should communicate your intent.

Align Your Message With Its Usefulness Over Time and Audience

You're about to write something. Think, is this something that might be valuable to more people beyond your immediate audience or recipient? What about in the future? Are you going to have to send a similar message the next time this situation occurs? Writing efficiently means limiting duplicate effort wherever possible. Avoid re-writing the exact same message slightly different audiences. Don't just fire-and-forget emails, but publish important information and email or instant message a link to it.

Writing to Inform or Educate

If your goal is to inform or educate, and writing in a one-on-one medium, there's a good chance your message would reach a wider audience if you published it and referred to it rather than putting the full message into an email or series of chat messages. Publishing information on how the team operates, where to find important resources, etc. in a wiki, README file, or FAQ is much more likely to be referenced and shared by many team members than putting the same detailed information into an email.

If you've just finished writing a brilliant email that explains a difficult concept perfectly or one person or just your team, before you hit send (or even after), consider publishing your brilliant explanation somewhere less ephemeral than email. Send a brief summary with a link, rather than an article disguised as an email, and your content may help a much wider audience for a much longer time.

But wait, won't some readers ignore the link? Of course, but they likely weren't going to do more than skim or read the first few sentences of your email, anyway. You're at least leading them to water - it's not always possible to make them drink.

Writing to inform also benefits the most from visuals. Screenshots, diagrams, hand-sketched notes, and more can all dramatically improve the effectiveness of educational written information. Don't put all that effort into an email that will perhaps be looked at once and then lost forever! Publish it somewhere where it can live on and evolve as needed over time.

Writing to Request Information

Quick and simple questions can usually be fulfilled via chat apps. Longer, more detailed questions might be better written as emails. Some companies use dedicated systems for technical questions, like their own [private Stack Overflow Team(https://stackoverflow.com/teams/pricing) (we use one of these to good effect in my devBetter group coaching program, for example), that provides easy search capabilities and multiple answers, voting, etc. The longer and more detailed the question, the more likely you should move it from chat to email to a knowledge base or issue tracker.

Some examples of questions and where you might best ask them:

"Does anyone know how to use (some software package)?" - Slack Channel or MS Teams team, maybe email

"What is the current status of issue 1234?" - Email. IM if you want a quick response.

"Why doesn't this code work (followed by 100 line code listing)?" - Stack Overflow or similar, perhaps with a message linking to its URL in Slack/Teams/etc.

If you're going to write an email to request information, try to only ask one question per email. If you write a lengthy email with several different parts, and ask a question in each part, it's extremely likely that you're only going to get an answer to one or a few of your questions, while some will be ignored. Or, if the reader is particularly diligent and wants to make sure they can answer all of your questions, you may not get an immediate reply, even if they can answer most of the questions immediately. Instead the email may sit while they research or consider their answer to a more difficult question, and in many cases the email may not get a response at all unless you follow up because other concerns will arise that put it into the back burner.

Writing to Start a Discussion

Certain formats are much better for having a discussion than others. Frequently real-time face-to-face (in person or via Zoom etc.) meetings are the best way to have such conversations, as long as the total number of participants isn't too large (typically more than 15 or 20 people). In my experience, email isn't great as a discussion format for complex topics. Real time chat programs are generally better, and have the advantage over meetings of providing a written log of the conversation that others who weren't available can still catch up on. For code discussions, I find that tools like GitHub issues or pull requests can be very effective, since they make it so easy to align the discussion around the code being discussed. This also has the benefit of keeping the discussion discoverable from the source code repository, rather than having it be lost in email or chat history when new developers join the team.

Writing to Request Action

If you need something from someone, your writing should make this very clear. Don't write a lengthy email with a bunch of points in it and then somewhere near the end mention that you're critically blocked because you need the reader to complete some task. If getting the reader to take action is the main point of your communication, you should increase the signal-to-noise ratio by putting the request front and center and by avoiding diluting your intent with other points. If there recipient needs something from you to perform the task, make sure it's included in the message, but background information or "by the way" extraneous information should be left out or sent separately. You can include something like "ACTION REQUIRED" in your subject if you want to increase the chance that it won't be ignored even further.

We all get a lot of emails, and we learn how to quickly triage them and get them out of our inbox. Emails act as a "to do" list for many people, so lean into this fact and make it clear which of your emails require them "to do" something, and which are just informational.

Using TO, CC, and BCC in Emails

If you just want to keep someone in the loop, but don't need anything from them directly, use the CC field rather than the TO field. Many people configure email categorization or filtering rules that let them deal with CC emails differently than TO emails (one they just need to read, the other they need to do something about). Similarly, you can use BCC if you want to inform someone of your communication without making it apparent to the recipient you're doing so. You can also use this to give yourself a copy of some correspondence if your email system doesn't already capture all of your sent emails or if you want to retain the email for some other use (like a backlog of docs you want to write based on your long explanatory emails, or another email account you want to have access to the messages).

Reusing Content

Avoid rewriting from scratch things you've already written. Make use of hyperlinks or copy/paste when you find that you need to say the same thing more than once to different audiences. When you find information or conversations that were in one medium but would be better in another, migrate them. You and another dev just had a great conversation on Teams about how to design a part of your application architecture? Copy/paste that into an Architecture Decision Record and send an email to the team with a link to it. Someone asks a question on in a Slack channel you've already answered before? Just send a link to your wiki page or blog post, perhaps with a quick note about how it applies to their situation. Need to send a weekly summary email to your manager about what you accomplished this week (a great habit even if they haven't asked you to do so)? Pull it out of your git commit messages and/or pull requests and link to the associated work items. The email will almost write itself.

Match Length to Intent and Medium

Have you ever been in a Slack/Teams/Discord discussion, with several people writing in quickly with their thoughts and reacting to one another's messages, and one user who keeps popping up "x is typing..."? After a few minutes, you might start to get worried about them, as their message never actually comes through. The beauty and effectiveness of realtime collaboration software stem from their instant nature. The feedback loop is short, and since threaded conversations often require more effort and break up a general chat, most messages rely on their proximity (in time and space in the channel) to make it clear which message or individual they're replying to. If you try to write several paragraphs as a single message in a fast-paced conversation, by the time you hit send the conversation may have long since moved on.

You can say the same thing in a series of shorter messages - there's nothing stopping you from sending one sentence at a time instead of several paragraphs in a batch. This lets folks react and respond to your words in real time, just as they would in a face to face conversation. Don't try to shoehorn email-style communication into real time chat. The same is true for SMS messages, which generally should be short and to the point, not long form articles. While generally shorter is better when it comes to email, you should avoid using email as a substitute for group collaboration. Unless it's your group's style, you usually want to avoid reply-all messages that just say "+1" or "Me too" or something similarly short. In fact, you should think hard before you reply all to any email with more than a couple of recipients.

Remember there's also an implied sense of urgency in real time communication, and much less of one in asynchronous communication. If you need to know something right now then a phone call, SMS, or IM are all much better choices than an email or a comment on an issue or a blog post. And just the same, if you don't need it right now, consider putting your request into an email rather than sending that IM at 1 o'clock in the morning to your team

Summary

Writing effectively and writing efficiently are closely related. To write effectively, you need to understand your audience, your intent, and craft your message in a way that's most likely to get the response you're seeking. To write efficiently, you want to do all of that, with as little effort as possible while achieving the largest reach. If you're having trouble writing effectively, focus on that first, but once you're confident in your writing, consider ways in which you communicate more efficiently as well.