Clarity is an underrated skill

I think clarity of communication is one of the most underrated skills as a developer. If the ratio of reading code to writing code is 10:1¹ then the ratio of talking about code to writing code must be 100:1, especially the more senior you get. Being able to define a problem or explain a scenario clearly, precisely and unambiguously should be something that, in my opinion, every developer strives to nurture.

To increase clarity in my own communication, I try and follow these three rules:

1. Make the implicit explicit.
2. Be succinct.
3. Avoid ambiguous pronouns.

Make the Implicit Explicit

Words like “clearly” and “obviously” can often be used to smuggle misunderstanding into a conversation, as they assume shared context and understanding of your audience which they may not have. This can exclude people and risks you talking at cross purposes with them - the obvious thing to them may not be the obvious thing to you.

Obviously we cannot implement a TurboRouter.

With this example, I may be thinking that we cannot do it because of the cost but you may be thinking that we cannot do it because it doesn’t solve our problem. We can strip out the “obviously” and just replace it with the reason why you think it is obvious.

We cannot implement a TurboRouter because it is too expensive for our budget this quarter.

Be Succinct

Include the relevant information and exclude everything else. What is relevant relies heavily on context.

The TurboRouter works by calling the inherited methods from the Router superclass which adhere to our router generic interface. However, instead of using a constant weight to assign routes, it uses Gamon’s algorithm to randomly assign a weight based on the migratory patterns of Canadian geese. This changes the routing time from O(n^2) to O(n) at peak times.

Whilst this may be relevant information when communicating to other developers, it may be irrelevant detail when speaking to a Product Manager. Something like this could be more suitable in the latter scenario.

In the upcoming project we are implementing a TurboRouter. The impact of this is that customers will experience less delay when connecting at peak times.

Avoid Ambiguous Pronouns

Ambiguous pronouns, such as “it” or “this” can make it unclear what you are referring to, especially in long or complex paragraphs.

The TurboRouter relies on the goose-based protocol, while the QuickRouter only has quadratical scaling. This will mean it is unreliable in production.

The “it” in the previous statement is ambiguous as to whether we are referring to the TurboRouter or the QuickRouter. We can remove the ambiguous pronouns to make our meaning clear.

The TurboRouter relies on the goose-based protocol, while the QuickRouter only has quadratical scaling. The goose-based protocol will mean the TurboRouter is unreliable in production.

I use these three rules every day to try and improve the clarity of my writing, but they are just a start. I found the Google Technical Writing course to be excellent in providing further tuition in the subject. A picture may be worth 1000 words, but 100 good words are worth 1000 bad ones.