Re: [PATCH v2 0/4] Use singular "they" when appropriate

On Fri, Jun 11 2021, Derrick Stolee wrote:

On 6/10/2021 6:58 PM, Ævar Arnfjörð Bjarmason wrote:

quoted

On Thu, Jun 10 2021, brian m. carlson wrote:

...

quoted

quoted

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 [ref]
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.

quoted

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
[ref] and more generally
look at the leftover hunks as noted in my
[ref]?