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

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

[Merlin (they/them) via GitGitGadget]

From: "Merlin (they/them) Patterson" <merlinpatt+githubgit@gmail.com>

These changes make this documentation more inclusive.
Using "male" and "female" as examples of gender is unnecessary.
The use of "it" shouldn't be used to refer to people even in an
  example of what not to use. People are never "it"s.
There's no need to specify a person or group of people that
  learned "they" is only plural.

Signed-off-by: Merlin (they/them) Patterson <merlinpatt+githubgit@gmail.com>
---
    docs: Update CodingGuidelines to be more inclusive
    
    These changes make this documentation more inclusive.
    
     * Using "male" and "female" as examples of gender is unnecessary.
     * The use of "it" shouldn't be used to refer to people even in an
       example of what not to use. People are never "it"s.
     * There's no need to specify a person or group of people that learned
       "they" is only plural.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1070%2Fmerlinpatt%2Fpatch-1-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1070/merlinpatt/patch-1-v1
Pull-Request: https://github.com/git/git/pull/1070

 Documentation/CodingGuidelines | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 711cb9171e0..ffd7fa9c0f4 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -552,9 +552,9 @@ Writing Documentation:
  Documentation/SubmittingPatches file).
 
  In order to ensure the documentation is inclusive, avoid assuming
- that an unspecified example person is male or female, and think
- twice before using "he", "him", "she", or "her".  Here are some
- tips to avoid use of gendered pronouns:
+ the gender of an example person, and think twice before using
+ "he", "him", "she", or "her". Here are some tips to avoid the use
+ of gendered pronouns:
 
   - Prefer succinctness and matter-of-factly describing functionality
     in the abstract.  E.g.
@@ -566,8 +566,8 @@ 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...
+     --short:: Should a person and/or program want shorter output,
+               he/she/they can...
 
     This practice often eliminates the need to involve human actors in
     your description, but it is a good practice regardless of the
@@ -586,15 +586,13 @@ Writing Documentation:
       versions.
 
   - If you still need to refer to an example person that is
-    third-person singular, you may resort to "singular they" to avoid
+    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.
+    learned that "they" is only used for third-person plural.
 
  Every user-visible change should be reflected in the documentation.
  The same general rule as for code applies -- imitate the existing

base-commit: 225bc32a989d7a22fa6addafd4ce7dcd04675dbf
-- 
gitgitgadget

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

[Junio C Hamano]

"Merlin (they/them) via GitGitGadget" <gitgitgadget@gmail.com>
writes:

>     These changes make this documentation more inclusive.

I am not sure about this claim, though.

>      * Using "male" and "female" as examples of gender is unnecessary.

It feels somewhat more excluding for those of us who are non-native
speakers to use a heavier-weight word "gender".  After all, it warns
against writing "he", "him", "she" or "her"---the reason why we warn
against the first two is because the author has to implicitly assume
the person in question is "male".  Similarly the latter two needs to
assume "female".  These two words, "male" and "female", are both
easier to understand to even non-native speakers like us, and at the
same time quite in line with the suggestion being offered.

Maybe the motivation behind this change is a misunderstanding that
somehow the original of what this patch touches says that "male" and
"female" are the only two possible values of "gender", but I cannot
read it that way even when I squint my eyes.

>      * The use of "it" shouldn't be used to refer to people even in an
>        example of what not to use. People are never "it"s.

People are never "it", but I do not think that is relevant.  Reading
the original of what this patch touches, the subject is either a
person or a program, and for program, referring to "it" would be
perfectly sensible, no?

>      * There's no need to specify a person or group of people that learned
>        "they" is only plural.

Again, this change assumes/requires too much knowledge of the
language, which is more excluding for non-natives who may think
there is only one kind of the English language taught everywhere in
the world uniformly unless told explicitly.  If you are familiar,
there may be "no need", but does it actively hurt those of you who
are familiar if the explanation gives such an example?  Removing it
may actively hurt those who did learn English as a second language.

So, I can applaud for the desire to be inclusive, but I am not sure
if the patch succeeds in doing so.

Thanks.

> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1070%2Fmerlinpatt%2Fpatch-1-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1070/merlinpatt/patch-1-v1
> Pull-Request: https://github.com/git/git/pull/1070
>
>  Documentation/CodingGuidelines | 16 +++++++---------
>  1 file changed, 7 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 711cb9171e0..ffd7fa9c0f4 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -552,9 +552,9 @@ Writing Documentation:
>   Documentation/SubmittingPatches file).
>  
>   In order to ensure the documentation is inclusive, avoid assuming
> - that an unspecified example person is male or female, and think
> - twice before using "he", "him", "she", or "her".  Here are some
> - tips to avoid use of gendered pronouns:
> + the gender of an example person, and think twice before using
> + "he", "him", "she", or "her". Here are some tips to avoid the use
> + of gendered pronouns:
>  
>    - Prefer succinctness and matter-of-factly describing functionality
>      in the abstract.  E.g.
> @@ -566,8 +566,8 @@ 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...
> +     --short:: Should a person and/or program want shorter output,
> +               he/she/they can...
>  
>      This practice often eliminates the need to involve human actors in
>      your description, but it is a good practice regardless of the
> @@ -586,15 +586,13 @@ Writing Documentation:
>        versions.
>  
>    - If you still need to refer to an example person that is
> -    third-person singular, you may resort to "singular they" to avoid
> +    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.
> +    learned that "they" is only used for third-person plural.
>  
>   Every user-visible change should be reflected in the documentation.
>   The same general rule as for code applies -- imitate the existing
>
> base-commit: 225bc32a989d7a22fa6addafd4ce7dcd04675dbf

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

[Ævar Arnfjörð Bjarmason]

On Wed, Feb 16 2022, Junio C Hamano wrote:

> "Merlin (they/them) via GitGitGadget" <gitgitgadget@gmail.com>
> writes:
>
>>     These changes make this documentation more inclusive.
>
> I am not sure about this claim, though.
>
>>      * Using "male" and "female" as examples of gender is unnecessary.
>
> It feels somewhat more excluding for those of us who are non-native
> speakers to use a heavier-weight word "gender".  After all, it warns
> against writing "he", "him", "she" or "her"---the reason why we warn
> against the first two is because the author has to implicitly assume
> the person in question is "male".  Similarly the latter two needs to
> assume "female".  These two words, "male" and "female", are both
> easier to understand to even non-native speakers like us, and at the
> same time quite in line with the suggestion being offered.
>
> Maybe the motivation behind this change is a misunderstanding that
> somehow the original of what this patch touches says that "male" and
> "female" are the only two possible values of "gender", but I cannot
> read it that way even when I squint my eyes.

Isn't that exactly what it's saying? I.e. for the purposes of the
English used in our documentation there's two grammatical genders "he
ran the program", "she ran the program" and gender-neutral "it/they ran
the program".

>>      * The use of "it" shouldn't be used to refer to people even in an
>>        example of what not to use. People are never "it"s.
>
> People are never "it", but I do not think that is relevant.  Reading
> the original of what this patch touches, the subject is either a
> person or a program, and for program, referring to "it" would be
> perfectly sensible, no?

Yes, as the person who wrote this originally (in
https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/) that's
what I was going for. It's referring to describing a program as "it".

>>      * There's no need to specify a person or group of people that learned
>>        "they" is only plural.
>
> Again, this change assumes/requires too much knowledge of the
> language, which is more excluding for non-natives who may think
> there is only one kind of the English language taught everywhere in
> the world uniformly unless told explicitly.  If you are familiar,
> there may be "no need", but does it actively hurt those of you who
> are familiar if the explanation gives such an example?  Removing it
> may actively hurt those who did learn English as a second language.
>
> So, I can applaud for the desire to be inclusive, but I am not sure
> if the patch succeeds in doing so.

Per what I noted the last time this was discussed I think that we should
mostly drop this section entirely in favor of some guidelines describing
how to actually write the docs that we do write, not what not to do in
the rare/nonexistent cases of using grammatical genders:

    https://lore.kernel.org/git/87pmwt1dz3.fsf@evledraar.gmail.com/

brian's follow-up provides a good example of what we try to aim for:

    https://lore.kernel.org/git/YMKTARn368Qzsqc2@camp.crustytoothpaste.net/

The thing that's uninclusive here is asking non-native speakers of
English who are trying to contribute to this project to grasp some
fairly advanced linguistic concepts.

I think it's fair to say that the use of "they" as a personal pronoun is
fairly new/novel English language as it's commonly understood. I.e. if
you talk to any person who's not a native-level speaker of English it's
a fair assumption that their introductory textbook didn't cover it.

As noted in those old threads I'm entirely sympathetic to the goal of
avoiding gendered language if it's a thing that matters for some
readers, which clearly it does[1].

It just demonstrably isn't relevant to our documentation in practice, so
this whole advice ends up being a bridge to nowhere. It's comparable to
us carrying C++ coding guide lines in-tree.

1. To be fair, I do find it a bit odd, but then again I'm a non-native
   speaker, and I'm unable to refer to even the monitor, keyboard and
   laptop I'm using to type this in my in my native language without
   assigning the three (different!) genders.

   I can assure the concerned native English speakers that by all
   accounts Iceland's got a rather good track record when it comes to
   gender equlity despite that :)

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

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

>> Maybe the motivation behind this change is a misunderstanding that
>> somehow the original of what this patch touches says that "male" and
>> "female" are the only two possible values of "gender", but I cannot
>> read it that way even when I squint my eyes.
>
> Isn't that exactly what it's saying? I.e. for the purposes of the
> English used in our documentation there's two grammatical genders "he
> ran the program", "she ran the program" and gender-neutral "it/they ran
> the program".

Yes, for the purpose of the language, there are only two grammatical
genders, "male", "female" (and "thing").  But my point was that the
documentation was not making any non-technical value judgement like
"genders outside these two are forbidden".

What I found problematic with the rewrite is that by moving from
more concrete examples ("avoid 'he' and do not assume 'male'") to a
more abstract wording ("avoid gendered pronouns"), it would burden
non-natives disproportionally more, and I do not see a clear benefit
to offset the downside.

I do not think it adds anything to discussion to repeat what was
already said, so I'll refrain from commenting on the other two
changes in the patch, but they posed the same problem to me.  I
cannot convincingly answer with "yes" to the question "does it
overall help inclusiveness? really? how?"

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

[Ævar Arnfjörð Bjarmason]

[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/pull.1070.git.git.1645029267415.gitgitgadget@gmail.com/
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 <220217.86a6epiyii.gmgdl@evledraar.gmail.com> here in full (sent Thu,
17 Feb 2022 10:51:35 -0500
as<CAFZ26y0VPVyAjq4Fh+CQRMu=J9rYZG6PQWpHFiWRKZJFb3aAEw@mail.gmail.com>):]

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.

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

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 3881 bytes --]

On 2022-02-18 at 23:18:35, Ævar Arnfjörð Bjarmason wrote:
> 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.

Singular they has been in common use for centuries.  It became less
common for many years because prescriptivists proposed using "he" to
refer to people of all genders, which was in common use for a long time,
until it was widely criticized as being sexist (and also, at times,
sounding bizarre).  "He or she" was then used in formal writing, but
that was also criticized as not being inclusive as well as being wordy
and awkward.  During this entire time, singular they has remained in
common use in speech and informal writing and is widely recognized as
part of the English language.

It's true that it is only now becoming more acceptable in formal
writing, but it is well known and commonly used in English as a whole
and has been for a long time.

I will also freely admit that for people who have learned English as a
second language sometime in the past, this would probably not have been
covered in the textbook.  As I continue to use Spanish, I learn things
about the language and how it's used today that differ from what I
learned when I started learning it formally over two decades ago, and
that's okay. Language evolves and as speakers of a second or third
language, we'll have to evolve with it.

> 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 agree, this context would be helpful.  Maybe, if we retain this, we
can just explicitly say, "Even though some non-native speakers may find
the use of singular they unusual, it is in fact common in English and
preferred in our documentation."

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

It is simply not the case that this is obscure.  As I've said in the
past, singular they, in the sense of referring to a single person whose
gender is unknown or irrelevant, has been in use since the 14th century
and has been used by William Shakespeare, Lord Byron, and Jane Austen.
It is routinely used for this purpose by fluent non-native speakers as
well (I have noted colleagues doing this).

I will admit that using they as the pronoun for a person whose gender is
known and who has explicitly requested the use of this pronoun is much
more recent, which probably dates to the mid 20th century (albeit at a
much lower frequency than today), but this is not the context in which
we are using the pronoun in our documentation.

It may be that for some readers it is the first time they've seen it,
but it will be far from the last if they continue to read English.
Understanding the main idea of a technical document in one's specialized
field (e.g., the Git documentation) is part of the CEFR B2 level, and at
that point, I'd expect the reader to have read numerous news articles
and online documents where this usage is common or becoming so.

As to your suggestion to this effect, I should point out that I'm fine
with removing this text from the documentation, as you suggested,
provided we can stop having extended debates about it on the list.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]