Subject: Re: [PATCH] docs: update coding guidelines to be more inclusive

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Sat, 19 Feb 2022 00:18:35 +0100

[You need to configure your E-Mail client to stop sending HTML E-Mail to
the Git mailing list. It's all being rejected by kernel.org. See
e.g. https://lore.kernel.org/git/[email-masked]/
where only your initial posting is visible, but not your replies.

It's also good etiquette on the ML not to top-post your replies, but to
reply inline. Except perhaps when not in reply to specific points, such
as this part of my reply :)

For other ML readers who weren't directly CC'd I'm quoting your reply to
my <[email-masked]> here in full (sent Thu,
17 Feb 2022 10:51:35 -0500
as<CAFZ26y0VPVyAjq4Fh+CQRMu=[email-masked]>):]

On Thu, Feb 17 2022, Merlin (they / them) Patterson wrote:

> Removing "male" and "female" allows for a broader statement of "don't assume any gender and always keep it gender neutral".
> What if I change it to remove the bit about the example person altogether?
>
> * In order to ensure the documentation is inclusive, think twice before using
>
> The example given starts off with people and has he/she/they/it in it. This ties "it" to he/she/they, making it sound like "it" also refers to a person.
> I don't think the program part makes sense as part of that example anyway. How about that be separated into its own example?
>
> * --short:: Should a person want shorter output, he/she/they can...
> * --short:: Should a program want shorter output, it can...

Yes, as the person who wrote this whole thing initially I don't really
stand by it, i.e. it was edited from a throwaway comment of mine.

For what it's worth I don't really find the he/it person/program of it
ambiguous, but what do I know?:)

Aside from that referring to an "it" in the context of our documentation
*is* something we need to do. Git the program is often (usually?)
invoked by other programs, not directly by human agency.

In any case, what do you think about this instead:
	
	diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
	index c37c43186ea..2bcb748aaa3 100644
	--- a/Documentation/CodingGuidelines
	+++ b/Documentation/CodingGuidelines
	@@ -600,12 +600,6 @@ Writing Documentation:
	      --short:: Use this to emit output in the short-format.
	      --short:: You can use this to get output in the short-format.
	      --short:: A user who prefers shorter output could....
	-     --short:: Should a person and/or program want shorter output, he
	-               she/they/it can...
	-
	-    This practice often eliminates the need to involve human actors in
	-    your description, but it is a good practice regardless of the
	-    avoidance of gendered pronouns.
	 
	   - When it becomes awkward to stick to this style, prefer "you" when
	     addressing the the hypothetical user, and possibly "we" when
	@@ -619,16 +613,10 @@ Writing Documentation:
	       Use this instead of --xyz. This option might be removed in future
	       versions.
	 
	-  - If you still need to refer to an example person that is
	-    third-person singular, you may resort to "singular they" to avoid
	-    "he/she/him/her", e.g.
	-
	-      A contributor asks their upstream to pull from them.
	-
	-    Note that this sounds ungrammatical and unnatural to those who
	-    learned that "they" is only used for third-person plural, e.g.
	-    those who learn English as a second language in some parts of the
	-    world.
	+  - Referring to users as a cast of characters (Alice, Bob etc.) or in
	+    the third-person singular is too obscure to worry about for the
	+    purposes of this style guide. Search the mailing list archive for
	+    "third-person singular" for more.
	 
	  Every user-visible change should be reflected in the documentation.
	  The same general rule as for code applies -- imitate the existing

> As for the part about removing "those who learn English as a second language in some parts of the world.", I stand by that.
> Even native English speakers also believe that "they" is only a third person plural. That's not restricted to non-native English speakers.
> Also, it's weird to give an example for this. Either a person learned that "they" can be both singular and plural or they didn't. Whether they learned English as a second or other language
> is irrelevant.
> How does providing an example benefit anyone?

...

On Thu, Feb 17 2022, Merlin (they / them) Patterson wrote:

> "It" and "they" shouldn't be grouped together. Examples using "it" must be separated from examples using "they". This prevents confusion around which word refers to what. And it ensures that
> a person is not thought of as an "it".
>
> This is why I suggested that I could split the example so "it" clearly refers to "the program" and can't be confused as referring to a person.
>
> As for removing the example about non-native English speakers, I gave my reasoning but I'll give it again. The example doesn't help anyone. A lot of native English speakers also think "they"
> can only be plural.[...]

I think this came about because of a previous discussion that you'll
find in the list archive where some native speakers were maintaining
that "they" in this context was widely accepted usage because it had
made it into some style guides single-digit years ago.

I.e. this was a perhaps flawed attempt to say something like "this
phrasing sounds weird, but it's actually correct".

As someone who speaks at least 4 languages regularly with levels of
proficiency ranging from native to something that sound as though I'm
trying to butcher the language, I can assure you that advice like that
*is* really useful to a non-native speaker.

I.e. whatever you or anyone else thinks about this usage of "they" it
*is* relatively obscure usage of English. I'd even bet that for some
readers of this document it's the first time they've ever seen it.

So just like the pronoun "thy", it's useful to add a small explanation
that it's in fact not a typo or something.

> Explicitly calling out non-native English speakers as making this
> mistake can have an alienating effect.

I realize I'm just shouting into the ether from my little soap box at
this point, but the alienating thing to non-native speakers isn't that
we might be told that our English isn't as good as that of non-native
speakers.

It's okey, really. We know.

It's the opposite, it's that a lot of people aren't assuming that others
who who want to participate in this project might have 1/10th of their
reading comprehension and reading speed when it comes to dense technical
documentation like this.

Because if they did we might have less of the "read this before you
contribute" documentation, or more narrowlry tailor it to practical
issues contributors are likely to encounter.

Which is why I've been maintaining (and still do) that removing most of
this is the right thing to do. It's clearly something anyone maintaining
our documentation is unlikely to encounter or have to worry about, and
therefore doesn't at all belong as a hurdle we put in the way of any new
contributor in the form of documentation we advise them to read before
they submit their first patch.