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

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

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:

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.

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.

Sure.

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.

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.

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.

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

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/