On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote: > > On Thu, Jun 10 2021, brian m. carlson wrote: > ... >> In many cases, saying less is better, I agree. If we don't need to >> refer to a human being, then we don't need to consider any pronouns for >> that human being. If we communicate things more simply with fewer >> words, then that's clearly better overall for everyone involved. >> Nobody's reading documentation for pleasure, after all. >> >> I do think that the recommendation that we refer to an anonymous user in >> a gender-neutral way still stands, though. Sometimes we will need to >> refer to the user or another human actor and that will be the most >> natural way to express the idea, so we should use gender-neutral >> language to do so. >> >> So roughly here, I'm in favor of both approaches. > > When do we need or even prefer to refer to a user like that? > > I haven't seen an example in our documentation that's actually better > off because we're talking about things as if two "people" we need to > invent pronouns for are interacting. > > Can anyone name one that'll stand up under scrutiny, i.e. once we can > look at it and see if we couldn't phrase it better by avoiding the issue > this series tries to address with a regex search-replacement? > > The diffstat of this series is only: > > 12 files changed, 22 insertions(+), 15 deletions(-) > > I've looked at all of them and I can't see one that wouldn't be better > if the relevant text was changed similarly to what I've suggested > upthread. > > That's why I don't think this proposal is useful. If we accept this > series we're going to be left with an active recommendation for a > pattern that's already almost nonexistent in our documentation. > > Perhaps that's because we're doing it 98% right already and aren't using > "he" or "she" but "they" or "their". The multiple ways you can use > "they" or "their" in the English language makes that hard to grep for. A > lot of our "they"'s are referring e.g. to a command-line option, or > "their" referring to "their arguments", as in the argv vector of a > program. Since the examples are already few in number, it is not an overwhelming amount of work to remove third-person singular pronouns from the necessary locations. Perhaps if there were more examples then such a conversion would be too difficult and we would want to use a more mechanical replacement with singular "they". My general approach (as specified in this v2) is: 1. Use singular "they" over "he" or "she" and other variants. 2. If you don't want to write "they", then avoid third-person singular pronouns. Your approach focuses only on item 2, giving this recommendation: * Avoid third-person singular pronouns. I think your change to CodingGuidelines is a bit verbose to get to that point, and makes it difficult to understand one goal is to avoid gendered pronouns, which I think reduces the chance that a new contributor would discover and understand that recommendation. A semantically similar addition would be: Avoid gendered pronouns such as "he/him" and "she/her". If necessary, alter your sentence structure to use singular "you" to refer to the reader or plural "they" to refer to multiple actors. > The skepticism about this being needed at all isn't an opinion I hold > about software documentation in general, but about software in Git's > problem space specifically. A change that says "don't use 'he' and/or 'she' unnecessarily" is important to encode as a project guideline so we can stop having discussions about their use whenever they are introduced in a patch. There is value in having this decision encoded, and the important thing from my standpoint is that we explicitly avoid gendered pronouns and can simply point contributors to that decision if we ever notice one being introduced. That reduces friction the same way that we decide where curly braces should be placed after an "if" statement. My preference continues to be singular "they" because it is an easy way to adapt natural sentence structures into an inclusive language. But if we decide that this grammar is too difficult for some readers to understand (due to English as a secondary language or other reasons to be more strict to older language patterns), then avoiding gendered pronouns entirely would satisfy my goals in this series. Thanks, -Stolee
