Re: [PATCH 4/4] CodingGuidelines: recommend singular they

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:

> From: Derrick Stolee <dstolee@microsoft.com>
> [...]
> If we use singular "they/them" pronouns instead of "he/him" or "she/her"
> pronouns, then we can avoid this congitive load on the reader.
>
> Using singular "they" is also incredibly efficient. Choosing a gendered
> pronoun is usually arbitrary between "he" or "she". Using constructs
> such as "he or she", "s/he", or "(s)he" are more complicated than
> singular "they".

Somewhat humorous & somewhat serious aside: Maybe it's just me, but when
I read "incredibly efficient" I was thinking more of an energy drink
filled with with nanites that would directly update my brain with the
documentation, not the minutia of how we go about wording things :)

Continuing; Snipping around a bit in your E-Mail (a sentence copied from
"[...]"  above:

> If the reader does not consider that pronoun to apply to them,
> then they can experience cognitive dissonance that removes focus from
> the information. [...]
> When choosing a gendered pronoun, that pronoun no longer applies to
> nearly half of possible readers. Even if we alternated between "he/him"
> and "she/her" perfectly evenly, we would still expect male and female
> readers to experience an incorrect pronoun half the time. However, some
> readers will not prescribe to either of these binary genders. Those
> readers hence suffer an incorrect pronoun the entire time. Singular
> "they" applies to every reader.

I'd expect most people to not actively read technical documentation and
try to personally actively ascribe themselves to prose that clearly
forms an example of something they may or may not do.

If that is how people commonly read documentation and find it
off-putting I'd expect gendered language to be the least of our
problems, since even with s/\bhe|she\b/they/g so much of what's left is
still referring to hypothetical situations most users won't want to find
themselves in.

Maybe I'm overthinking this, but per the above I'd think if this is a
problem with losing the reader that we'd need more structural solutions
to it in the common case, e.g. more guarded language that you should not
read further if you don't care about XYZ aspect of the technical feature
we're about to discuss.

> Perhaps due to similar reasons, official style guides have changed their
> stance on singuler "they" in recent years. For example, the APA style
> guide changed their official recommendation in 2019 [1]. The MLA
> handbook also references helpful ways to use singular "they" [2]. While
> not fully endorsing it, the Chicago Manual of Style has removed its
> blanket ban on singular "they" [3] (the previous recommendation was to
> only use "it" as a singular non-gendered pronoun).
>
> [1] https://apastyle.apa.org/blog/singular-they
> [2] https://style.mla.org/using-singular-they/
> [3] https://libraries.indiana.edu/chicago-manual-style-singular-pronoun-they
>
> While not all styleguides are updating their recommendations, we can
> make a choice as a project to adopt the concept because of the
> efficiencies above, as well as the benefits of increased inclusion.
>
> To futher justify singular "they" as an acceptable grammatical concept,
> I include the careful research of brian m. carlson who collected their
> thoughts on this matter [2] (lightly edited):

It seems strange to attempt to summarize the previous discussion in the
cover letter and here thoroughly, and make not even a passing mention of
the counter-argument I presented to it in [1]; which resulted in most of
the replies to that thread, and which the maintainer you're trying to
get to apply this patch seemed to agree with. More on that at the end.

> If we refer to a specific person, then using a gendered pronoun is
> appropriate. Examples within the Git codebase include:
>
> * References to real people (e.g. Linus Torvalds, "the Git maintainer").
>   Do not misgender real people. If there is any doubt to the gender of a
>   person, then use singular "they".

Sure.

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

I don't think using the Alice & Bob examples is necessarily a problem,
but while we're discussing writing inclusive technical docs I think
their use is probably a bigger problem than the pronoun issue you're
presenting here.

That's because often using those characters is an overly clever
reference to their use in crypto circles, and thus the developer often
ends up writing documentation that simply assumes that the fact that
"Eve" is the "Eavesdropper" is obvious to the reader.

Whenever I read documentation like that I end up Googling it and end up
at the "Cast of Characters" section in the relevant Wikipedia page, just
to see if I'm missing something. It doesn't make for accessible
documentation.

I think the use in Documentation/gittutorial.txt that you didn't end up
changing is a good example of something that would be better rewritten
as "you" and then referring to "bob" as some generic remote repository
instead, I haven't seen an overly clever example of Alice/Bob/Eve
etc. in git.git's docs, but maybe it's there somewhere.

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

It seems strange to exclude arbitrary uses of passages from Beowulf and
quoting of Plato in diff/merge tests from a commit that's otherwise
arguing that arbitrary uses of "he" or "she" is going to lose the reader.

After all we do have a need to refer to the hypothetical user in some
manner in the prose of our documentation, but those tests will pass if
we rot13 the gendered-pronoun-using relevant text, or otherwise replaced
all the input with gibberish following similar whitespace rules.

> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index e3af089ecf26..78cd399f7cf5 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -648,3 +648,8 @@ Writing Documentation:
>   inline substituted text+ instead of `monospaced literal text`, and with
>   the former, the part that should not get substituted must be
>   quoted/escaped.
> +
> + When referring to an anonymous user, use singular "they/them" pronouns
> + as opposed to choosing between "he/him" and "she/her". [...]

I do think most of the changes in patches 1-3 were an obvious
improvement and that we could really do with some general extension of
preferred prose in the "Writing Documentation" section you're
modifying.

I think advice about that should really start more generically, this
seems like losing the forest for the trees. E.g. do we write things
like:

    --force: You can use this to force the command to do XYZ

Or:

    --force: Skip sanity checks, do XYZ

I'd like to think that we'd mostly prefer the latter, and that also
nicely sidesteps the issue you're tackling here.

I think any such advice would be better off by stating that our usual
preference is to describe things in the abstract, continuing to
preferring to assume that we're talking directly at the user:

    You can use use --force to disable the safety.

As opposed to needlessly introducing more verbose and possibly gendered
prose:

    Should the user wish to disable the safety features, they can use
    the --force option.

This patch hunk also seems like it would be better worked into the first
3-4 paragraphs of "Writing Documentation" somehow, rather than tacking
it at the end. That's where we've started to discuss US v.s. UK English,
following existing conventions etc.

> [...] Do not use more complicated constructs such as "he or she" or
> "s/he".[...]

I note that one thing you didn't tackle at all in [1] & downthread is
the problem we have that's really not present in the style manuals
you're referring to.

That is, once we've done with avoiding verbosity per the above &
preferring "you" over anything else we're usually left referring to a
generic concept of an OS user.

Such a thing does not have any gender, and need not be tied to any
particular life form. It's usually something authors of manuals of style
don't need to consider outside of sci-fi novels.

I think we'd do well to prefer imitating how e.g. C library docs usually
deal with that over any MOS, which is to just say something like "a user
with permission xyz can...." or whatever. It's just weird to think of
say a git command run by my sshd or www-data user as a "they", just as I
wouldn't use "he" or "she".

> [...] This recommendation also applies to code comments and commit
> messages.

Since you were seeking ACKs in the CL this is overall a NACK from
me. For reasons noted in the thread starting at [1] so I won't repeat
most of that here; but briefly: I do think extending this to commit
messages in particular is over-reaching.

Our installed documentation is one thing, but commit messages are much
closer to the prose people are personally comfortable with, every hurdle
we put to accepting patches, particularly ones that seem arbitrary and
without good technical reasons are also something that harms inclusion &
project velocity.

This whole thing also started in reply to one patch submitted by Lénaïc
Huard (a non-native speaker of English), which he promptly re-rolled
after this whole pronoun thread started. Grepping around with:

    git log --grep='\b(he|she)\b' -i origin/master

And mentally grepping out changes referring to specific people (just
generic examples), I see one change in 2021, then you've got to go back
to 2017 to find the next one (I just skimmed this, maybe I missed some),
you very quickly get to 2014.

I think I'd feel even stronger that we didn't need this in transitory
commit message examples even if it were more common, per the argument in
[1].

But given how rare it is anyway seeking to enforce a policy on commit
messages just seems like an over-reaction to a specific recent
contribution.

In summary: My "NACK" is mostly on the "and commit messages". Just
because *generally* we should be less nitpicky about personal preferred
prose there, I'd feel the same way about insisting on US English only or
whatever. We should be forgiving in what we accept there.

Installed docs are another matter entirely, I'm very much in favor of
having some extensions to the existing style guide there. I do think as
argued above we should start more generically, and it's not just
bikeshedding. As argued above I think we should mostly be recommending
different prose entirely, as apposed to now actively recommending "they"
(which if you discuss e.g. "a user" mostly won't be needed).

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