Writing Skills

Once you’ve determined who your audience is and how you should approach the conversation, the next thing to be aware of is the channel you’re using to communicate. Whether the conversation takes place in person or through a written form of communication such as chat or email will determine how you approach the conversation.

The first channel we’ll dive into is written communication. As a programmer, you’ll be reading and commenting on a lot of code reviews throughout your career, and how you communicate your thoughts and ideas in writing can determine how well those ideas are received by your coworkers.

Code Reviews

Code reviews are often one of the poorest areas of communication between programmers, which is unfortunate because it’s also one of the most important. Constructive comments from senior developers are one of the best tools to help you become a better programmer because you’re receiving direct feedback on how you can improve your code and your logic. Whether it’s more concise syntax, bringing clarity to your logic, ensuring maintainability, improving performance, or handling edge cases you didn’t think about, the act of having someone else peer review your work will improve your technical skills.

Unfortunately, code reviews can often be intimidating experiences for developers because it’s easy to feel like the reviewer is criticizing the programmer and not their code. The wrong words or the wrong tone can do more harm than you may realize, so it’s important to be cautious of this when reviewing and commenting on another’s code. It’s always best to stick to constructive feedback, and you should never personally attack the programmer for coding a solution a certain way, even if it’s wrong.

There are numerous ways to solve programming problems, and the best solution may not always be apparent to the person assigned to the task. While it may seem easy to disagree with someone’s code because you believe there’s a better way to solve the problem, criticizing their thought process or their implementation is the wrong way to go about it.

To build healthy relationships with your coworkers, it’s imperative that you stick to constructive criticism during code reviews. It doesn’t help anyone if your comment that the code is wrong or that it’s inefficient. Instead, explain why their solution is suboptimal and, more importantly, offer advice on how they can improve their code.

Let’s look at examples of two different types of comments you may see during code reviews, and why one is better than the other.

This comment doesn’t help the programmer at all because it doesn’t explain why the code will cause a performance issue, and it doesn’t offer a solution for how to fix the issue. It’s possible the programmer was lazy when writing their algorithm, but it’s also possible they may not even be aware their code is inefficient. The commenter comes off as abrasive, and the programmer who wrote the code may take their criticism personally, which could lead to indecisiveness and self-consciousness the next time they submit their code for review.

First, it’s less aggressive if you approach the comment as a question, rather than a statement. That way, you’re asking the programmer if they had considered your concerns, and it gives them an easy way to admit they hadn’t thought about that aspect when coding their solution, without trying to embarrass them.

Next, the comment offers a suggestion for how the programmer can improve their solution. Perhaps they were so caught up in getting to a working solution that they completely missed the opportunity to improve the efficiency of their algorithm. That doesn’t necessarily mean they’re a bad programmer by any means, so don’t make them feel like they are.

Another aspect of this comment is that it avoids using the word “you” and replaces it with “we” and “us.” By doing so, you’re signaling to the programmer that they are part of a team and that you’re all in this together.

Senior engineers tend to focus more on the success of the team as a whole, rather than just themselves, and it’s the small details like this that go a long way if you want to show that you’re a team player. Try not to single out programmers when offering feedback on their code. You’re all on the same team, and it’s everyone’s responsibility to deliver the highest quality code possible. It’s always better to stress the importance of the team and acknowledge that the code is owned by everyone and not a single person. In doing so, you’ll build confidence in your teammates and they’ll take your feedback seriously.

Now let’s look at the next way in which you’ll communicate with others through writing, which is in your project management system.

Ticketing Systems

There’s a good chance your team is using some kind of bug tracking or project management system. These tools help teams plan, organize, and track new features, tech debt, and bugs as tickets make their way through the development process and into production. Ticketing systems can get complicated very quickly with multiple people moving tickets around, creating subtasks, setting deadlines, and marking certain tickets as high priority.

Many programmers seem to despise these tools because they are heavy on process and always seem to get in the way. There are complex workflows, planning meetings, and coming up with arbitrary estimations for tickets—all of which sometimes feels unnecessary. While it may seem like these tasks take time away from actually writing the code they’re meant to track, these tools are important for project managers to stay organized and even more important for the management team to track progress on larger projects and to plan out longer-term goals that align with the company’s strategy.

Given the complexity of these tools, it’s important to make sure you’re communicating clearly on your tickets as you move them through the pipeline. When you create a new ticket, provide as much detail as possible. Don’t assume that other developers on your team will understand where to find the bug, how to reproduce it, or why a certain part of the code should be considered technical debt and needs to be cleaned up.

Software engineers can be lazy now and then; we’ve all been there before. There’s nothing worse than pulling in a ticket to work on and finding almost no information to go on. There may be a title and a one-sentence description. How do you know how to reproduce the issue if it’s a bug? How do you know if it’s a high-priority feature request from an important customer? How do you know if it’s tech debt that’s not really an issue but the developer who filed it felt like the code was just a bit messy? It’s sometimes impossible to know these things when there’s no information to work off of, and as a developer, it’s frustrating when you are assigned these kinds of tickets.

There’s almost no information on this ticket! There’s no context to work off of when it comes time to plan the next development cycle, except that a bug exists. It’s not even clear if the bug still exists because there’s no instructions on how to reproduce it.

Furthermore, it’s possible this particular report is complex, with multiple export settings, and the bug only exists for a specific configuration setting. If you pick up the ticket and try to reproduce this bug, the report’s export functionality might work fine for you because you don’t have the application in the same state as the person who reported the issue.

There’s also no indication of any acceptance criteria, which is a set of predetermined requirements that must be met in order for the product owner to mark the ticket as complete. In other words, how will we know the bug is actually fixed? It’s important to lay out this information up front, before the development work begins, so there is a clear finish line to know when you’re done. Doing this helps reduce scope creep and keeps the developer focused on solving the original problem instead of making additional unrelated changes in the process.

So, how would you improve this ticket so the issue is clearly communicated?

You can already see that there’s much more information in this ticket that will help prioritize this work during planning sessions and will help the developer reproduce the bug when they pick up the ticket. The ticket provides a stack trace to help the developer pinpoint exactly where the error is thrown on the server, as well as steps to reproduce the bug. Notice how the description states that the bug happens when exporting in CSV format, which is also helpful. Without that, someone may try to reproduce the bug and be able to successfully download the report in Excel format.

Lastly, the acceptance criteria are clearly defined so the project manager knows exactly what requirements need to be met in order to mark the story as complete. This helps the developer focus on fixing the actual bug rather than optimizing the code or cleaning up a part of the codebase unrelated to the actual bug itself.

You’ll be creating lots of tickets throughout your programming career, so it’s important to build good habits now. While they may seem trivial to you at first, these small details make a big difference. Junior developers tend to overlook this aspect of software development because they’re focused on writing code. Sure, writing code is important, but keeping information organized in the issue tracking system is another piece to the puzzle when it comes to documenting, planning, and delivering software.

When writing tickets, it’s helpful to think of it as if you’re communicating with someone in the future. Whether you’re communicating with yourself or someone else, your goal should be for whoever picks up the ticket tomorrow, next week, or next year to have all the information they need to work on the task. If they pull up your ticket a month from now and there’s no information except for a title, there’s a good chance they’ll just close the ticket and move on to something else because they don’t know enough context to pull it into the next development cycle.

Which brings us to the next point—closing tickets. While your version control system acts as a historical record of changes made to your codebase, your project tracking system acts as a historical record of all implemented features, bug fixes, and technical debt that has been paid down over the years. It acts as a paper trail for the work your team has accomplished and also offers insights on how efficient your team was in delivering the work.

Leaving notes and details about each ticket (and updating any relevant documentation) as the work happens allows project managers and new engineers to look back and get important context for why some action was taken on a ticket. A new engineer may find a reference to a ticket number in a git commit or a comment in the codebase that they can pull up and get additional context around why a specific piece of code was written.

It’s important to add comments and give good reasons when closing tickets, because other people may find that information useful in the future. Sometimes multiple developers will report separate tickets for the same bug, or there may be tickets that overlap in scope. Other times the change may be so low in priority that it’s closed to reduce the clutter during a ticket grooming session. Other times the ticket may not be relevant anymore because the bug has already been fixed or priorities have changed. Regardless of why the ticket is no longer a priority, it’s always a good practice to add a comment giving a reason for why you’re closing the ticket and choosing not to work on it.

Here are a few examples:

The worst thing you can do is to close a ticket without any context because whoever pulls up that ticket in the future will have no idea why this work was never done. It takes less than a minute to add a one-sentence comment about why you’re closing a ticket, so try to document why you’re doing something when making changes.

And lastly, not everyone will be able to monitor the comments and activity for each individual ticket, so it’s helpful to tag the relevant people when adding your comments. It’s easier to keep track of ticket activities when you get email or chat notifications when things happen, rather than having to continuously monitor each ticket for new comments or movements in their status.

Following these few tips while working in your project management system may not seem like much, but your manager will appreciate good communication skills, even in asynchronous channels. In general, the more information you can provide, the better, especially when it comes to updating others on the progress of specific tasks in your tracking system. As you work your way towards a senior role, building good habits when working in your project tracking system will let everyone benefit from the knowledge and information you share.

Communicating over Chat

Chat systems have been around for decades and have been adopted by companies of all sizes, from startups to public companies. They’ve even become valuable tools for open-source projects with the rise of Slack, Microsoft Teams, Discord, and many others. While you’re probably already experienced with chat communications, here are a few things to keep in mind when using them a professional setting. It may be simple and obvious advice, but it goes a long way when exchanging information with others.

Similar to tickets in your project tracking system, communicating over chat systems is asynchronous in nature. Although chat is much more real time, you may or may not get a response right away. Conversations can happen quickly in group chats, or they can happen over the span of hours or days. If you need an immediate response, consider other channels of communication. If you’re in the office, talking to someone in person is the quickest way to get the answers you need. If you’re working remote, try to get them on a video call or at the very least, a voice call. Recognizing which conversations are best held over chat and which ones are better off in a different channel will help avoid miscommunication and will get you the information you need in a timely manner.

One habit that is good to get into is to simply acknowledge when someone asks you to take a look at something. You may need to ask someone to take a look at your pull request or to review a design document, and it’s sometimes frustrating if you need an answer right away but your request just sits there without any response.

When someone asks you to review something, give a quick response like “Taking a look”, “Looking now”, or “Will take a look in 15 minutes after this call” to let them know that you saw their request when you will look at their document. When someone reaches out to have you look at something, it’s usually urgent enough to warrant asking for a review. This small habit lets the other party know that you’re working on it so they aren’t met with complete silence on their end.

Different channels are meant for conversations around different topics. Your company may have a few different channels like #general, #marketing, #engineering, #industry-news, or a #random channel. The larger the company, the larger the audience in each channel, which is why it’s important to respect the channel topic when posting or holding a conversation with someone. It’s insensitive to hold personal conversations with others in public channels. If possible, try to move those kinds of conversations to a direct message channel with the person you’re talking to.

On the other hand, sometimes it’s best to hold certain conversations in public rather than in a direct message. If it’s an urgent conversation or a discussion about a topic that multiple people should be aware of, then it would be helpful to discuss in a public channel, because it allows others to follow the conversation along with any decisions that are made.

Communicating over Email

By now, we’re all comfortable communicating over email, so I won’t get too deep into details here. Similar to communicating over chat, try to determine if email is the right channel for the kind of information you’re trying to communicate. Before sending an email, consider other communication channels and determine if it’s better to ping someone over chat or hop on a video call. Sometimes a 15-minute video call is more efficient and effective than multiple emails back and forth with other people.

Urgency is also another thing to consider and may dictate which communication channel is best. Sometimes it’s best to pick up the phone or hop on a video call to discuss something time-sensitive. Alternatively, if the conversation isn’t time-sensitive, email could be a good asynchronous option.

Regardless, email is still widely used throughout the world, and there are certain conversations where it’s the best option, such as communicating with people outside of your organization. Unfortunately, email conversations tend to be slow, and important points can be easily misinterpreted. Let’s look at a couple of things you can do to improve your communication over email.

Subject Lines Matter

Use the subject line to get your point across. Lots of people scan subject lines when they’re busy or in a hurry, so try to make yours specific and to the point so that someone scanning their inbox will know they need to open your email.

Always try to be as specific as possible, while keeping the subject line concise. A good subject line should hook the recipient in and stand out among the clutter of an inbox.

Better subject lines are clear, to the point, and worth the extra few seconds it takes to think of something specific. They go a long way in helping make sure your emails are read and not skipped over by someone skimming an inbox.

Keep It Short

Some people get hundreds of emails a day, which leads to email fatigue. When things are moving quickly in the office or when there’s a time crunch to meet a deadline, not everyone will have the time to read every email they get. People frequently scan emails to look for relevant information, and a good way to guarantee your email doesn’t get read is to send a big wall of text to your recipients.

Keep emails short. The shorter the better. And try to get your point across in the first or second sentence. This helps people that are in a rush and gets them the relevant information they need. Not everyone will read to the end of your emails, so if you’re asking someone a question in the third paragraph, don’t assume they will see it and respond with an answer.

Use Formatting

Additionally, a good way to make your emails easier to scan and make your most important information stand out is to use text formatting for your important points.

• Use bullet points or numbered lists to make it easy to convey different options or lists.

• Use bold fonts to stress importance. The bold lettering will usually be the first thing someone reads, so use it sparingly and only for the most important one or two points you’re trying to make.

• If you have to write a long explanation, break it up into multiple paragraphs. There’s nothing worse than a huge wall of text, and multiple paragraphs makes it easier to read.

• Consider underlining or using font colors to highlight the most important information. If you do this, do it consistently within a single email. Keep in mind that certain colors can be hard to read if they don’t contrast well with the background. And using colors to highlight some text can draw attention away from other parts of the text which may be overlooked.

  • Use red to highlight disclaimers or risks that are critical for people to know. You can even preface the sentence with “Disclaimer:” or “Important:” in boldface or red to add more impact.

  • If you’re responding to an email and answering someone’s questions, highlight your answers in a different color like blue. This makes it easier to differentiate between the original author’s questions and your answers.

Use @ Tags

In group emails, if you need to direct a question to a specific person or direct specific people to handle action items, it’s helpful to use @ tags. It’s usually a good idea to combine these with bold formatting to make sure your requests are seen.

When someone sees you’ve tagged their name, you’re more likely to drive action or get a response from them, but as always, use them sparingly otherwise they lose their effectiveness.

Don’t Send Immediately

Whatever you do, do not send the email immediately after you finish writing. There’s no undo once you hit send, so taking a few minutes to proofread your email could save you from embarrassment in the future.

Sending emails with grammatical errors can actually hurt how people perceive you and how much they trust your opinions, so it’s crucial to catch any mistakes before hitting send. There are tools, such as Grammarly, that can highlight grammar mistakes in real time and help you catch simple mistakes and clarify your writing.

Even if you’re using tools to help catch errors, you should still proofread your own writing. Reread your email, and then reread it again. Try to combine or remove sentences completely in order to shorten the email to just the necessary information. Only after you’ve proofread your email multiple times should you hit send.

Now that we’ve covered some things you can do to improve your written communication, let’s look at verbal communication.