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

[Junio C Hamano <gitster@pobox.com>]

"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