Co-references are Confusing Your Writing
Co-reference is a linguistic property when two or more expressions refer to the same thing, the referent. Here is an example:
The text highlighted in coral is the entity and its following two coreferences. The text highlighted in light blue is another entity and its coreference.
Sarah is a Graduate Student at UW. She loves working in the Medical Research Lab at the school. Her extra time is spent hiking and painting.
In documents that refer to multiple parties, groups, or organizations, each taking different actions - using co-references can lead to confusion. An example of a potentially confusing statement due to co-reference usage would be:
The Product Team discovered a high severity risk in their product and reported it to Application Security. They triaged it and determined that it was launch blocking and recommended a remediation. Then they created a ticket for it.
The yellow highlighted co-references are potentially confusing, and the red highlighted co-references are definitely confusing.
The first red highlighted “they” could refer to either the Product Team or Application Security, leaving the reader to either rely on other knowledge of the event or process to figure out what “they” was referring to.
In the second instance of “they,” there is very little to indicate which group created the ticket. Furthermore with the third instance of “it,” there is very little to indicate whether a ticket was created for the security issue or the remediation.
In general, refrain from co-references and err on the side of making clear declarative statements. A clearer re-write (the changes are highlighted in green) of the example above would be:
The Product Team discovered a high severity risk in their product and reported the risk to Application Security. Application Security triaged the risk and determined that it was launch blocking and recommended a remediation. Then Application Security created a ticket for the risk.