git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, gitster@pobox.com,
	sandals@crustytoothpaste.net, stolee@gmail.com,
	jrnieder@gmail.com, emilyshaffer@google.com,
	Andrei Rybak <rybak.a.v@gmail.com>,
	Felipe Contreras <felipe.contreras@gmail.com>,
	Robert Karszniewicz <avoidr@posteo.de>, Jeff King <peff@peff.net>,
	"Kerry, Richard" <richard.kerry@atos.net>,
	Phillip Susi <phill@thesusis.net>,
	Johannes Schindelin <Johannes.Schindelin@gmx.de>,
	Bagas Sanjaya <bagasdotme@gmail.com>,
	Derrick Stolee <derrickstolee@github.com>,
	Derrick Stolee <dstolee@microsoft.com>
Subject: Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
Date: Tue, 15 Jun 2021 18:19:53 +0200	[thread overview]
Message-ID: <87a6nryt51.fsf@evledraar.gmail.com> (raw)
In-Reply-To: <f06092a9053e40d93c4ec94b7fbbb1b8d563957b.1623766273.git.gitgitgadget@gmail.com>


On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote:

> [...]
> * References to fictional people with clear genders (e.g. Alice and
>   Bob).

I mentioned in the feedback on an earlier round[1] that aside from your
goals, these would be better rewritten. I've just submitted a series[2]
to do that; perhaps you can look at that and see if you think there's
still a reason to explicitly exclude these.

> * Sample text used in test cases (e.g t3702, t6432).

FWIW that's another unaddressed-by-you question I had in an earlier
round[1].

> [...]
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index e3af089ecf26..0282f836548a 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -551,6 +551,34 @@ Writing Documentation:
>   documentation, please see the documentation-related advice in the
>   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:
> +
> +  - Removing the example person might make the sentence more
> +    clear and efficient.  Instead of saying "The programmer
> +    chooses between X and Y as she sees fit", it is clearer to
> +    say "Valid choices are X and Y".
> +
> +  - If you need to talk about an example person, then try using
> +    second-person to allow the reader to be that example.  For
> +    example, "If you want X to happen, you'd pass option Y",
> +    instead of "If the user wants X to happen, she'd ...").
> +    Alternatively, replace the single example with more than one
> +    person and use plural "they", such as "Interested readers
> +    can read 'git log -p README' to learn the history in their
> +    ample spare time" instead of "an interested reader" learning
> +    in "his" spare time).
> +
> +  - If you absolutely need to refer to an example person that is
> +    third-person singluar, you may resort to "singular they" (e.g.
> +    "A contributor asks their upstream to pull from them").  Note
> +    that this sounds ungrammatical and unnatural to those who
> +    learned English as a second language in some parts of the
> +    world, so should be avoided unless the earlier techniques
> +    fail to improve the sentence.
> +
>   Every user-visible change should be reflected in the documentation.
>   The same general rule as for code applies -- imitate the existing
>   conventions.

In the same E-Mail that you copied the original version of this new text
from[3], Junio suggested, mostly in reference to my [4]:
    
    I tend to agree that Ævar's approach to guidelines is to cover more
    general readability tips, not necessarily focusing on avoidance of
    gendered pronouns, let alone encouraging of "singular they".  I
    think that is overall a good approach to advance the "let's make
    sure the document is easier to read by everybody" goal than
    mechanical "he and she are bad, let's use they" does.

To be fair he does go on to say something that suggests to also go for a
version of your approach here, i.e. that we still have some reference to
"they" over "he" and "she". I've got no problem with that, but he also
said (comments in [] are mine):
    
    If we were to go that route [(of copying Junio's version from [3])],
    I think the first two points [(i.e. the first two bullet-points you
    incorporated above)] (which I didn't give enough thought to be even
    called a "draft") should be replaced with something like what Ævar
    wrote in his write-up.

So your version here does none of that, and we're mostly left with advice
about what not to do in the demonstrably obscure edge case of gendered
language in our docs (as evidenced by the diffstat).

But we aren't helping contributors much with with positive examples of
what to do unrelated to that, i.e. for documentation they could actually
be expected to write or maintain. I.e. general prose guidelines for
common the cases of discussing command-line options, program behavior,
user interaction etc.

Anyway, I don't think I'll be participating in this topic any
further. It seems you're not interested in pursuing alternate approaches
that accomplish your goals, or in responding to specific point-by-point
feedback on your series from myself and others.

I do think it would be a much better and respectful use of everyone's
time on this ML if you clearly stated your unwillingness to deviate from
the narrow approach in the initial version of a series you're
submitting.

Maybe I'm wrong and you are willing to incorporate something like more
general prose that accomplishes most or all of your narrow goals as a
side-effect, but right now it seems you're not.

If we're going to make some use of the collective time spent by a lot of
people on-list reading the documentation you're suggesting to change,
that'll have to be done in a series that would textually conflict with
yours (and which Junio would need to clean up), or in something that
would build on top of your more narrowly focused work.

1. https://lore.kernel.org/git/875yyp4fun.fsf@evledraar.gmail.com/
2. https://lore.kernel.org/git/cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com/
3. https://lore.kernel.org/git/xmqqr1h51dce.fsf@gitster.g/
4. https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/

  reply	other threads:[~2021-06-15 16:44 UTC|newest]

Thread overview: 124+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
2021-06-07 17:32     ` Derrick Stolee
2021-06-07 17:42       ` Andrei Rybak
2021-06-07 18:21       ` Ævar Arnfjörð Bjarmason
2021-06-10  7:44     ` Johannes Schindelin
2021-06-10 14:35       ` Felipe Contreras
2021-06-07 21:36   ` Felipe Contreras
2021-06-09 18:47     ` Phillip Susi
2021-06-09 20:26       ` Felipe Contreras
2021-06-11 15:40         ` Phillip Susi
2021-06-11 17:03           ` Felipe Contreras
2021-06-10 18:30       ` Derrick Stolee
2021-06-11  0:16         ` Junio C Hamano
2021-06-11 16:00         ` Felipe Contreras
2021-06-12 14:02         ` Phillip Susi
2021-06-08  1:18   ` Junio C Hamano
2021-06-08  8:51     ` Kerry, Richard
2021-06-08 23:21       ` Junio C Hamano
2021-06-09 13:13         ` Derrick Stolee
2021-06-10  3:11         ` Junio C Hamano
2021-06-08 17:33   ` Emily Shaffer
2021-06-08 18:03     ` Felipe Contreras
2021-06-09 13:44       ` Kerry, Richard
2021-06-09 17:44         ` Felipe Contreras
2021-06-25 14:30           ` Kerry, Richard
2021-06-09  4:48     ` Junio C Hamano
2021-06-10  8:18     ` Johannes Schindelin
2021-06-10 14:42       ` Felipe Contreras
2021-06-14 22:10       ` Robert Karszniewicz
2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
2021-06-07 17:20     ` Derrick Stolee
2021-06-10  8:20     ` Johannes Schindelin
2021-06-07 19:02   ` Junio C Hamano
2021-06-07 21:44     ` Felipe Contreras
2021-06-08 17:36   ` Emily Shaffer
2021-06-07 16:57 ` [PATCH 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-08 17:37   ` Emily Shaffer
2021-06-10  8:36   ` Johannes Schindelin
2021-06-10 19:53     ` Derrick Stolee
2021-06-11  9:55       ` Johannes Schindelin
2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
2021-06-08  1:47     ` Felipe Contreras
2021-06-07 18:56   ` Junio C Hamano
2021-06-07 19:05     ` Derrick Stolee
2021-06-08  0:05       ` Junio C Hamano
2021-06-10 21:34       ` brian m. carlson
2021-06-10  8:39     ` Johannes Schindelin
2021-06-07 20:00   ` Felipe Contreras
2021-06-09 18:29     ` Phillip Susi
2021-06-09 20:18       ` Felipe Contreras
2021-06-07 20:20   ` Robert Karszniewicz
2021-06-07 22:18     ` Felipe Contreras
2021-06-08  7:10   ` Jeff King
2021-06-08  8:11     ` Felipe Contreras
2021-06-09 13:23       ` Derrick Stolee
2021-06-09 15:20         ` Felipe Contreras
2021-06-10 22:06     ` brian m. carlson
2021-06-11 16:11       ` Felipe Contreras
2021-06-08 17:39   ` Emily Shaffer
2021-06-09  4:44     ` Junio C Hamano
2021-06-09 13:27       ` Derrick Stolee
2021-06-07 20:10 ` [PATCH 0/4] Use singular "they" when appropriate Felipe Contreras
2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
2021-06-09 13:54   ` [PATCH v2 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
2021-06-09 15:33     ` Felipe Contreras
2021-06-09 13:54   ` [PATCH v2 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
2021-06-09 15:41     ` Felipe Contreras
2021-06-09 13:54   ` [PATCH v2 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-09 13:54   ` [PATCH v2 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-09 15:50     ` Felipe Contreras
2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
2021-06-09 17:22     ` Felipe Contreras
2021-06-10  2:03     ` Junio C Hamano
2021-06-10  2:28       ` Junio C Hamano
2021-06-10  3:30       ` Felipe Contreras
2021-06-10 22:32     ` brian m. carlson
2021-06-10 22:58       ` Ævar Arnfjörð Bjarmason
2021-06-11 16:32         ` Felipe Contreras
2021-06-11 17:18         ` Derrick Stolee
2021-06-11 20:38           ` Felipe Contreras
2021-06-13  7:17           ` Ævar Arnfjörð Bjarmason
2021-06-15  6:02             ` Junio C Hamano
2021-06-15 13:36               ` Derrick Stolee
2021-06-15 17:03                 ` Felipe Contreras
2021-06-14  0:47           ` Junio C Hamano
2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 1/4] doc: avoid using the gender of other people Felipe Contreras via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 2/4] comments: avoid using the gender of our users Felipe Contreras via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason [this message]
2021-06-15 17:26         ` Felipe Contreras
2021-06-16  2:47         ` Junio C Hamano
2021-06-16  5:06           ` Junio C Hamano
2021-06-16  9:26             ` Bagas Sanjaya
2021-06-16 17:44             ` Derrick Stolee
2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason
2021-06-16 23:22               ` Felipe Contreras
2021-06-17  0:09               ` Junio C Hamano
2021-06-17 13:22                 ` Derrick Stolee
2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
2021-06-17 17:06                     ` Felipe Contreras
2021-06-17 15:25                   ` Felipe Contreras
2021-06-18  0:26                   ` brian m. carlson
2021-06-18 16:12                     ` Felipe Contreras
2021-06-17 15:23                 ` Felipe Contreras
2021-06-17 15:58                 ` Ævar Arnfjörð Bjarmason
2021-06-18  0:53               ` brian m. carlson
2021-06-18  7:24                 ` Ævar Arnfjörð Bjarmason
2021-06-18 16:40                   ` Felipe Contreras
2021-06-19  7:03                 ` Junio C Hamano
2021-06-28 22:32                   ` Junio C Hamano
2021-06-29  1:31                     ` Felipe Contreras
2021-06-29  1:53                     ` Derrick Stolee
2021-06-29 12:29                       ` Ævar Arnfjörð Bjarmason
2021-06-17 15:12             ` Felipe Contreras
2021-06-17 14:46           ` Felipe Contreras
2021-06-15 17:08       ` Felipe Contreras
2021-06-12  4:40 ` [PATCH 0/4] Use singular "they" when appropriate Bagas Sanjaya
2021-06-12 14:19   ` Phillip Susi

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87a6nryt51.fsf@evledraar.gmail.com \
    --to=avarab@gmail.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=avoidr@posteo.de \
    --cc=bagasdotme@gmail.com \
    --cc=derrickstolee@github.com \
    --cc=dstolee@microsoft.com \
    --cc=emilyshaffer@google.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=gitster@pobox.com \
    --cc=jrnieder@gmail.com \
    --cc=peff@peff.net \
    --cc=phill@thesusis.net \
    --cc=richard.kerry@atos.net \
    --cc=rybak.a.v@gmail.com \
    --cc=sandals@crustytoothpaste.net \
    --cc=stolee@gmail.com \
    --subject='Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox