On Fri, Jun 11 2021, Derrick Stolee wrote:
> 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, [...]
It is, because I'm not trying to get to that point at all, and I haven't
been convinced by your proposed series that we need to. I think it's
implicitly covered more generally applicable advice.
> 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.
I think a new contributor is going to be confused by your proposed
modification to the CodingGuidelines because it doesn't activtely tell
you how to do things in the common case, but just that you should avoid
this one obscure edge case.
I'm not saying my hastily written alternative is perfect, but it is a
start at providing some much more general advice that would also have
the effect of bypassing the issue you're concerned about, would it not?
> 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.
Or, if we just fix these existing occurrences as a one-off there'll be
no existing examples of it in-tree, and as people tend to imitate
existing documentation they're unlikely to introduce new
occurrences.
Even before any discussion of an explicit recommendation the number of
occurrences is tiny compared to the volume of documentation we have.
If and when Felipe's <20210611202819.47077-1-felipe.contreras@xxxxxxxxx>
is applied how small is the diff you'll still have rebased on top of
that?
There's a cost/benefit trade-off between noting something in
CodingGuidelines, meaning that all contributors going forward will have
to read it and understand it, and just fixing a rare issue as a one-off.
I've provided examples of e.g. binutils, C library etc. documentation
that covers similar problem spaces, I'm fairly sure most/all of that
documentation was written in a way that satisfies your criteria without
the need for any specific advice on this point.
>> 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.
I'd probably agree with you if this was anything as common in our
documentation as missing {} if/else braces are in our code.
Due to the relative rarity of the documentation issue you're fixing I
can't think of a comparison other than: There's probably also plenty of
generic issues in our code that if fixed, would result in a diffstat
similar to your "12 files changed, 22 insertions(+), 15
deletions(-)".
Assuming your series and Felipe's overlaps (I haven't tried rebasing it
myself) a "9 files changed, 13 insertions(+), 14 deletions(-)" would be
deducted from that.
It doesn't follow that an issue of that rarity belongs in the
CodingGuidelines. Maybe there are still convincing reasons to include
them, I just don't think you've provided any.
It seems to me that any future proposed addition of an elaborate example
where we're gendering the command-line utility or the UID of some OS
user can be changed in a way that satisfies your criteria because it's
overly verbose and imprecise.
> 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.
Wouldn't it also satisfy your goals to re-roll on top of
<20210611202819.47077-1-felipe.contreras@xxxxxxxxx> and more generally
look at the leftover hunks as noted in my
<87a6nz2fda.fsf@xxxxxxxxxxxxxxxxxxx>?
