On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote: > From: Derrick Stolee <dstolee@xxxxxxxxxxxxx> > [...] > 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@xxxxxxxxxxxxxxxxxxx/
