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.
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.
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.
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.
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.
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 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.