Many forms of technical communication (functional specification, sprint planning, test plan, etc) need to demonstrate clarity. Unfortunately, clarity is often sacrificed – sometimes unconsciously – by an excessive use of ambiguous references.
In theory, a pronoun replaces the use of a noun. This is typically witnessed in the use of a personal pronoun (e.g. he/his/him) to replace the name of an individual. However, such a reference can not be vague. Failing to do that will cause a confusion to the reader.
When you write something, from your perspective, all the references are (extremely) obvious. Unfortunately, this is not always the case when someone else consumes the information. Here is a typical example, I am sure you have seen this in one form or another. Imagine that there is a problem with your service and the customer calls you up for an inquiry. After some discussion, you summarize the situation as follows (as an e-mail or incident ticket):
They found that the router was not configured properly. Joe gave me a call, but at that time I was busy with our team troubleshooting another customer.
Fortunately, Jack was online. Later, they summarized the finding and sent it to me. We don’t know exactly how this happened, but he assured us that they are working on that.
At some point, this information is forwarded to another person, maybe even multiple times. Since the problem is severe enough, it reaches the CEO and possibly even got forwarded further down the chain of the command. Another executive gets the memo and that person is having a hard time deciphering the content due to the lost context:
Who are they in “they summarized…”? Does that refer to Jack and Joe? Or perhaps another team?
Who are we in “We don’t know…”? Is it supposed to mean Jack and I? Perhaps Joe and I? Or even Jack, Joe, and the author?
And what about he in the same sentence? Is that Jack or Joe? It’d better be Jack.
What is this us referring to? The same folks as we in the beginning of the sentence?
Fixing the problem of these vague pronoun references is easy. Whenever possible, refer to the exact individual or group of people. Bonus point: narrow it down to a particular person by stating their full name and/or their department.
Michelle (Ops team, ACME) found that the router was not configured properly. Joe (PM, ACME) gave me a call, but at that time I was busy with Diana troubleshooting another customer (XYZ Corp).
Fortunately, Jack was online. Later, Joe summarized the finding and sent it to me. Diana and I don’t know exactly how this happened, but Jack assured the executive team that Joe and Michelle are working on that.
Both we and they are powerful personal pronouns. So powerful that it is hard to separate the former (a group of people including myself) with the latter (people other than us) without understanding the full context. Hence, when there is a potential for a confusion, the use of such pronouns must be banned.
Imagine a functional specification that is sprinkled with we and they all over the places. How do you interpret every single reference?
- we = the author, vs they = the rest of the world
- we = product manager, vs they = engineering, sales, marketing
- we = this business unit, vs they = some other business units
- we = the company, vs they = the customers, the partners
- we = human, vs they = zombies, aliens
To make things worse, the interpretation is hardly consistent throughout the document. Sometimes we in the beginning refers to the different group of people than another we at another place.
If you ever teach a child to tie their shoes, you know that it could be challenging at times. In fact, using the left lace vs right lace references will be downright impossible to follow. Now, there are many solutions and one of them is by using absolute references: red lace vs yellow lace!
Let us eliminate ambiguous references. Clarity triumphs.