In the fast-paced world of software development, brevity is often hailed as a virtue. Software engineers, with their affinity for efficiency, are notorious for distilling complex concepts into succinct messages–sometimes even a little too succinct.

While the skill of summarizing has its merits and uses, there are instances where more words can actually lead to greater clarity. In this article, we’ll explore how engineers can benefit from embracing a more expansive approach to communication.

The Curse of Conciseness

In our quest for efficiency, we software engineers sometimes fall into the trap of using too few words and creating more confusion and misunderstanding, thereby creating more work in an effort to create more efficiency. This tendency can be observed across various communication channels, from emails and Slack messages to requirements documentation and feedback to clients, teammates, and management.

Email, Slack, or Teams

Picture this: you receive an email from a colleague that contains a single sentence explaining a critical issue. While brevity is appreciated, a few more words in this email could offer you some valuable context, ensuring that you fully grasp the scope of the issue, the options available, their pros and cons, and the urgency of solving it.

The same is true in messaging platforms like Teams and Slack. It’s easy to fire off a quick response to someone without providing the necessary background information or details.

When collaborating within a team, clarity is paramount. While it might seem more efficient to send a one-liner about a bug or a feature request, providing additional information and content will often help teammates understand the issue, minimize follow-up questions, and find a better, faster solution.

Documentation

Clear and comprehensive requirements and technical documentation are both foundations of successful software project. Engineers sometimes err on the side of brevity in these documents, assuming that everyone shares their level of familiarity with the project, business rules, architecture, and code. However, taking the time to elaborate can prevent costly misinterpretations down the line.

For example, what permission level does this feature apply to, and what other roles can’t access it? Are there circumstances, even if they seem obvious, where this feature works differently or isn’t available at all? Is there another seemingly obvious way to do this, and if so, why did you decide not to do it that way?

Answering all of these less obvious questions from the perspective of an outsider can help ensure that anyone reading your documentation will be on the same page.

Feedback

In providing feedback, whether it’s code review comments, pull request feedback, or design suggestions, a more detailed explanation can be immensely valuable. Instead of merely stating, “This doesn’t work,” take the opportunity to elucidate why and offer possible solutions. Refer to the specific screen and state of that screen that you’re referring to, so whoever reads it understands the context.

Finally, if the feedback is something personal or related to a person’s performance, make EXTRA sure that you use more words to make sure you don’t miscommunicate or hurt feelings.

The Power of Elaboration

So, how should software engineers shift their thinking about adding more words to their communication arsenal? Below are a few suggestions:

Context is King

More words can provide context, offering a broader view of the issue or task at hand. This context empowers colleagues to better understand the situation and make more informed decisions.

Give The Background

What seems clear to one person may not be as evident to another. It’s easy to assume someone already has the same thoughts or experiences in their head as you, but that’s often not the case. By articulating thoughts more thoroughly, engineers can avoid making assumptions about their audience’s knowledge or perspective.

Avoiding Worst-Case Assumptions

When information is lacking in detail, human nature tends to fill the void with worst-case assumptions, often leading to unnecessary stress or misunderstandings. It’s essential to provide clear and comprehensive information to avoid these misunderstandings.

Better Facilitate Collaboration

Elaborating on your ideas fosters collaboration. It encourages discussions, sparks creativity, and ultimately leads to more innovative solutions. Someone else, when hearing your thinking or motivations, might have a new idea pop into their head or might be able to correct bad information that you have.

Prevent Frustration

Clear communication is the cornerstone of successful teamwork. By using more words to articulate their thoughts, engineers can minimize the risk of misunderstandings, reducing the need for costly revisions and making their teammates feel more efficient and connected, thus reducing the chance of frustration.

Striking a Balance

Of course, the goal is not to replace brevity with wordiness. Instead, it’s about finding the right balance between the two. Recognizing when more words are warranted and using them judiciously can significantly enhance communication within engineering teams. By embracing this approach, engineers can provide the context, avoid assumptions, facilitate collaboration, and prevent misunderstandings. It’s time to let our words flow, software friends!

So, the next time you find yourself typing a one-liner, try to see it from an outside perspective and consider whether a few more words might just be the key to better clarity and collaboration.