Skip to content

Instantly share code, notes, and snippets.

@0xabad1dea
Last active June 18, 2022 18:01
Show Gist options
  • Save 0xabad1dea/8870b192fd1758743f66 to your computer and use it in GitHub Desktop.
Save 0xabad1dea/8870b192fd1758743f66 to your computer and use it in GitHub Desktop.
Singular They in Technical English

Guidelines for Singular They in Technical English

by 0xabad1dea, December 2014

This document is an RFC of sorts for increasing the adoption rate of Singular They in technical English. This is not an ultimatum; this is not shaming anyone who has done otherwise; and this is definitely not applicable to any other language.

What is Singular They?

Singular They is the use of the they-pronoun to signal an individual of any gender or unknown gender. For example, the sentence "the user, if he prefers, can change the text color" becomes "the user, if they prefer, can change the text color." You will notice that it remains in the plural declension. This is not the grammatical issue that it may initially seem, because "you" already works the exact same way: "you are" rather than "you is", etc.

Why bother?

The tech industry has a gender gap problem. One way to combat it is to stop actively reinforcing the assumption that the user is male. When we use "he" as the pronoun of abstract individuals, we are reflecting our cultural problem in our language. We can change our language to serve our needs better.

Some documents use constructs such as "he or she" and "he/she" but this is rightly criticized as unwieldy. Some try arbitrarily switching it up or counterweighting with plain "she". There is another issue aside from elegance of constructs: an ever-increasing number of people, many of them in tech, are embracing non-binary gender identities. This trend is only going to accelerate. Outside of adopting an entirely new "artificial" pronoun (which isn't out of the question: again, we can change language), Singular They is the best-fit solution. It has a long attestation in English usage and fits a pattern already known to fluent speakers.

We have a responsibility to our communities to be actively inclusive. Paying attention to our pronouns is a small but real and quantifiable way we can demonstrate it.

How do we implement it?

Check your existing documentation for descriptions of non-specific people such as users, administrators, and adversaries which use "he" or a combination construct. You may also wish to check for diagrams which use the same clearly gendered icon for all users, a fairly common antipattern.

Document a policy that new documentation is expected to use Singular They. If someone slips up, don't lash out at them; simply correct it like any other grammatical slip-up.

Note that "Alice and Bob" documentation is fine; in this case the alternating genders are used to help the reader differentiate between different participants in a protocol.

Singular They works just like Plural They. Some people prefer "themself" over "themselves" and this has an attestation going back centuries. The writer of this document prefers "themself" but "themselves" should not be treated as incorrect.

Here is a more comprehensive example of Singular They:

If the user wishes to check if a host is responsive, they can use the "ping" utility built into their operating system. They can use either the IP address or the hostname as the argument to the command. When they execute "ping", an ICMP packet is sent from their machine off into the wild internet and, if the host is up, bounced back to them. They will be able to see for themselves exactly how long each ping took to cross the distance.

But I heard-

The most common objection to Singular They – that it is grammatically plural – has already been addressed. Singular You declines the exact same way as Plural You and yet this rarely causes any confusion; when absolutely necessary "you all" works nicely and so does "they all".

English was originally a tri-gender language (not a bi-gender one, like many Romance languages). Over time we have removed almost all forms of grammatical gender from the language, with he/she/it pronouns being the last remnant. However, for cultural reasons, calling a person "it" is generally unacceptable. Hence, by pushing for higher deployment of Singular They, we can help English along on its centuries-long arc of de-emphasizing gender where it is not relevant.

@matt-d-rat
Copy link

I completely support this. Great idea, clear and well written.

@ultimape
Copy link

While writing a user stories I often have a particular individual being used as an example. Would it be appropriate to use the genderized version:

while investigating my mom's use of ...
... when *she* presses...

or would this stylistic notion suggest I rewrite it as if it were a gender neutral story?

Another concern I've ran into. While doing IT work, I have hit some confusion in the past while referring to clients as 'they' and other technicians not knowing who I was talking about. I was often misinterpreted as creating a generalization of users instead of speaking of one user in particular. Would you happen to know of any tricks to avoid this kind of gotcha's and head-off any cultural preconceptions bleeding in and making this style difficult?

I've been substituting "they" with "the user" in these cases - but I don't like that this sets up an implicit power dynamic between 'us and them' as it can remove thoughts of empathy vital to creating a good experience.

@aredridel
Copy link

Specific people -- "my mom" and "she" should respect that person's identity. However, in general documentation, "they" for any, unknown, or an arbitrary person is best.

@ApopheniaPays
Copy link

ApopheniaPays commented Jul 5, 2021

Coming at this very late- that's what you get for posting new gists after a break of years and sharing the link to Twitter- but I just wanted to add the comment that I always thought "one" was the best genderless pronoun, even if it sometimes comes off as officious.

I'm not sure even wrestling with these issues isn't a sign that one just needs to go back and make the passage in question more succinct. There are other ways to be both more precise and concise, and avoid the sorts of superficial grammatical problems that for some reason pique certain dimwits, providing what I think is all-around better technical writing:

To check if a host is responsive, one can use the operating system's "ping" utility. The argument of the command can be either the IP address or the hostname. When executing "ping", one's machine sends an ICMP packet off into the wild internet, which, if the host is up, is bounced back to it. "Ping" then provides a figure for exactly how long each packet took to cross the distance.

To my ear, fewer pronouns, and no gender bias, but at least as clear, meets my strict Strunk & White pedantry standards, and has the added plus that it won't lead to me having to listen to my small handful of unfortunately less progressive friends complain that someone is depriving them of their liberty by using words "wrong".

Not that it really matters- as long as you're avoiding reinforcing the gender assumptions about any participant, a mission I totally agree with. But I've just never personally been quite comfortable with the singular "they" myself, I feel like it's kind of a band-aid solution.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment