'This' considered harmful

I wrote about Google's Technical Writing course before, tl;dr, if you're a software engineer, and you haven't yet read through Google's Technical Writing course: I recommend it.

One thing I didn't highlight in my previous post was the section "Words". As they aptly note in the introduction to that section:

We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words.

Indeed.

The first half of the "Words" section explains how to use terms consistently, and how to introduce and correctly use acronyms.

But the part I want to highlight in this post is the commentary on ambiguous pronouns: it, they, their, this, that.

These words are red flags 🚩 and should give you pause as you read or write them. Why? Because these pronouns can easily obfuscate what you are trying to express.

From the course:

Such pronouns are analogous to pointers in programming. Like pointers in programming, pronouns tend to introduce errors. Using pronouns improperly causes the cognitive equivalent of a null pointer error in your readers’ heads. In many cases, you should simply avoid the pronoun and just reuse the noun.

A recent example: A comment of "What is the use case for this?", in response to a long thread about a feature update with various social and technical considerations. Does "this" refer to the feature, the proposed modifications, or the one of the particular solutions mentioned in the discussion?

Or the word "it":

Extracted from the AbstractFoo base class, which was in turn factored out of DatabaseFoo. Foo was introduced as a narrow interface for Bar. It avoids legacy types such as Baz.

Does "it" refer to Foo? Probably. But would be nice to avoid extra mental work for the reader by specifying this directly.

One also finds "it" as the starting point of a sentence using passive voice, which is another good reason to be careful when writing "it".