How Readability Reduces Errors in Judgment
No small number of keystrokes have been spent enumerating the whys and hows of writing readable code. Readability improves the developer experience and makes seeing potential issues much easier. We might even say that by writing readable code, we reduce errors in judgment.
To illustrate the point, let’s consider the following example of using the “positive” form of variable names with Boolean logic:
var inactive = true;
vs
var isActive = false;
When instantiated, it seems innocent enough until we start creating conditions. Then our brain must make sense of “not inactive,” which actually means “active.” You can see how you can quickly get your bits flipped around.
But what about other communications we make? Have you ever considered improving the “readability” of your chats, emails, or interactions to reduce errors in judgment?
Let’s take our positive / negative example and consider a sentence you might find in an email. Which of the following statements is more clear and easier to consume?
We will not build the dashboard module at this time. There is not enough user feedback to validate which widgets and reports to include.
The team continues to complete user research around the widgets and reports for the proposed dashboard. We will determine the next steps and prioritize this feature on the product roadmap after we have a better understanding of our users’ needs.
Even neuroscientists have found that it takes human brains longer to process negative statements (see: https://neurosciencenews.com/language-adjectives-neuroscience-26207/). And if we are forcing our brains to work harder to understand the meaning, it only takes a small leap to imagine that by making our communication easier to understand, we are more readily able to catch mistakes or misses when seeking to create a shared understanding around building a software product and all of the various logistics and project management.
But you might wonder, what other ways can I make my communications more readable? The following is by no means an exhaustive list, and there are plenty of other resources for searching technical communication sources, but here is my top five:
- Consider your audience
a. Are they someone who will read paragraphs in detail, or do you need to put the single action item at the top?
b. Are they technical or non-technical?
c. Are there any terms you should define or phrases to avoid given this person’s context?
d. Is there anything else you know about this person that might allow you to tailor your message in a way that helps them understand the message best? - Know your goal or mission in sending a message or a particular interaction
a. What are you trying to achieve with this communication?
b. Am I trying to write something in an email that should be shared in person? Or on the other side, am I capturing appropriate artifacts and breadcrumbs from my in-person interactions? - Utilize formatting and diverse structure to provide appropriate emphasis
a. Bolding action items or deadlines will draw attention
b. Using lists or bullets helps visually group and order thoughts - Reduce all the fluff – keep it concise
a. If it takes many words to explain a concept or send a message, consider if you need to unpack or process further before sending. This might be a great moment to revisit if you understand your audience and goal in this communication.
b. Common words you can strike from sentences without losing any meaning: just, very, only, somewhat - Remove all negative language
a. As mentioned above, by forcing yourself to restate in a positive format, statements are clearer and reduce the effort needed to be taken by the reader
At the end of the day, this is simply one way to help reduce miscommunication with both internal and external stakeholders in the products we are building. The more we have a shared understanding, the less frustration, mistakes, and errors in judgment we will see throughout the entire software development lifecycle.
Please share your thoughts! Drop a comment on other ways you seek to make your communication “readable.” What other tools have you found helpful in achieving a shared understanding in all communications?
