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

Junio C Hamano [off-list ref] writes:

FWIW, I am not happy with this version for that reason, either.

I wonder if replacing the first two bullet points ("Removing" and
"If you need to talk about") above with what was added to the
CodingGuidelines by the "succinct matter-of-factly description" in

https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/

would be sufficient.

So, here is what I plan to queue on top of these four patches to
replace my "not even draft" garbage with what you wrote, with a bit
of copyediting.

Comments?

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 605f924981..476b840d30 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines

@@ -546,28 +546,43 @@ Writing Documentation:
  twice before using "he", "him", "she", or "her".  Here are some
  tips to avoid use of gendered pronouns:
 
-  - Removing the example person might make the sentence more
-    clear and efficient.  Instead of saying "The programmer
-    chooses between X and Y as she sees fit", it is clearer to
-    say "Valid choices are X and Y".
-
-  - If you need to talk about an example person, then try using
-    second-person to allow the reader to be that example.  For
-    example, "If you want X to happen, you'd pass option Y",
-    instead of "If the user wants X to happen, she'd ...").
-    Alternatively, replace the single example with more than one
-    person and use plural "they", such as "Interested readers
-    can read 'git log -p README' to learn the history in their
-    ample spare time" instead of "an interested reader" learning
-    in "his" spare time).
-
-  - If you absolutely need to refer to an example person that is
-    third-person singluar, you may resort to "singular they" (e.g.
-    "A contributor asks their upstream to pull from them").  Note
-    that this sounds ungrammatical and unnatural to those who
-    learned English as a second language in some parts of the
-    world, so should be avoided unless the earlier techniques
-    fail to improve the sentence.
+  - Prefer succinctness and matter-of-factly describing functionality
+    in the abstract.  E.g.
+
+     --short:: Emit output in the short-format.
+
+    and avoid something like these overly verbose alternatives:
+
+     --short:: Use this to emit output in the short-format.
+     --short:: You can use this to get output in the short-format.
+     --short:: A user who prefers shorter output could....
+     --short:: Should a person and/or program want shorter output, he
+               she/they/it can...
+
+    This practice often eliminates the need to involve human actors in
+    your description, but it is a good practice regardless of the
+    avoidance of gendered pronouns.
+
+  - When it becomes awkward to stick to this style, prefer "you" when
+    addressing the the hypothetical user, and possibly "we" when
+    discussing how the program might react to the user.  E.g.
+
+      You can use this option instead of --xyz, but we might remove
+      support for it in future versions.
+
+    while keeping in mind that you can probably be less verbose, e.g.
+
+      Use this instead of --xyz. This option might be removed in future
+      versions.
+
+  - If you still need to refer to an example person that is
+    third-person singular, you may resort to "singular they" to avoid
+    "he/she/him/her", e.g.
+
+      A contributor asks their upstream to pull from them.
+
+    Note that this sounds ungrammatical and unnatural to those who
+    learned English as a second language in some parts of the world.
 
  Every user-visible change should be reflected in the documentation.
  The same general rule as for code applies -- imitate the existing

-- 
2.32.0-241-g31cd86ad06

On 16/06/21 12.06, Junio C Hamano wrote:

+  - If you still need to refer to an example person that is
+    third-person singular, you may resort to "singular they" to avoid
+    "he/she/him/her", e.g.
+
+      A contributor asks their upstream to pull from them.
+ > +    Note that this sounds ungrammatical and unnatural to those who
+    learned English as a second language in some parts of the world.
  

I'm also confused and found that using singular they may sound odd. So 
IMO either avoid referring to third-person singular (gendered pronouns) 
or write using plural actors. In the case above it should be 
`Contributors ask their upstream to pull from them, potentially with 
reviews`.

A prime example of rewriting using plural actors is in "doc: avoid using 
the gender of other people" patch [1], which said the diff:

I'm OK with using they in plural context, but not as singular they.

[1]: 
https://lore.kernel.org/git/20210611202819.47077-2-felipe.contreras@gmail.com/

-- 
An old man doll... just what I always wanted! - Clara

On 6/16/2021 1:06 AM, Junio C Hamano wrote:

Junio C Hamano [off-list ref] writes:

quoted

FWIW, I am not happy with this version for that reason, either.

I wonder if replacing the first two bullet points ("Removing" and
"If you need to talk about") above with what was added to the
CodingGuidelines by the "succinct matter-of-factly description" in

https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/

would be sufficient.

So, here is what I plan to queue on top of these four patches to
replace my "not even draft" garbage with what you wrote, with a bit
of copyediting.

Comments?

...

+  - Prefer succinctness and matter-of-factly describing functionality
+    in the abstract.  E.g.
+
+     --short:: Emit output in the short-format.
+
+    and avoid something like these overly verbose alternatives:
+
+     --short:: Use this to emit output in the short-format.
+     --short:: You can use this to get output in the short-format.
+     --short:: A user who prefers shorter output could....
+     --short:: Should a person and/or program want shorter output, he
+               she/they/it can...
+
+    This practice often eliminates the need to involve human actors in
+    your description, but it is a good practice regardless of the
+    avoidance of gendered pronouns.

I wasn't a huge fan of this "example first" approach, but you did
a good job of tying it to the purpose and the rest of the
recommendations.

+  - When it becomes awkward to stick to this style, prefer "you" when
+    addressing the the hypothetical user, and possibly "we" when
+    discussing how the program might react to the user.  E.g.
+
+      You can use this option instead of --xyz, but we might remove
+      support for it in future versions.
+
+    while keeping in mind that you can probably be less verbose, e.g.
+
+      Use this instead of --xyz. This option might be removed in future
+      versions.
+
+  - If you still need to refer to an example person that is
+    third-person singular, you may resort to "singular they" to avoid
+    "he/she/him/her", e.g.
+
+      A contributor asks their upstream to pull from them.
+
+    Note that this sounds ungrammatical and unnatural to those who
+    learned English as a second language in some parts of the world.

This version looks good to me. It is probably worth adding Ævar in
a Co-authored-by line.

Thanks,
-Stolee

On Wed, Jun 16 2021, Junio C Hamano wrote:

That mostly-my-draft was hastily a written one-off, perhaps this is
better and a more exhaustive discussion of common cases:

  - Discussing command-line options, and program functionality:

    Prefer succinctness and matter-of-factly describing functionality in
    the abstract.  E.g.

     --short:: Emit output in the short-format.

    Avoid more verbose constructions, such as:

     --short:: Use this to emit output in the short-format.
     --short:: You can use this to get output in the short-format.
     --short:: A user who prefers shorter output could....
     --short:: Should a person and/or program want shorter output, he
               she/they/it can...

  - Addressing the reader:

    Address the reader of the documentation directly with "you",
    e.g. "you can do xyz".

  - Discussing Git, "the command" etc.:

    Use "we" when discussing how the program might react to the user, or
    perhaps "git" or "the command", e.g.:

        we might store the data[...]
        git will emit[...]
        the command will[...]

  - Discussing other users:

    When referring to other users on the same system prefer talking
    about "a user" or "another user". There's usually no reason to
    invent a cast of characters with names, titles and hobbies.

    Your OS's users don't cleanly map onto any particular people, a user
    of git might be having a merge conflict with another person, or an
    automated commit from a cron daemon.

    We prefer the style typical of standard library adn system tooling
    documentation in this and most other cases, you can look at the
    documentation of chmod(2) and other commands, syscalls and libraries
    that deal with UIDs or GIDs for examples.

  - Discussing other systems:

    As with discussing other users, git might interact with other
    systems over the network. In these cases we also avoid a cast of
    characters, preferring to talk about concepts like "fetching data
    from a remote", having a conflict with "diverging histories" etc.

The references to "gendered prounouns" etc. are gone, perhaps there's a
good reason to re-include them, but the point of "isn't that issue
solved by recommending an orthagonal approach?" is one of the many
things Stolee hasn't been addressing in the threads related to this
series.

To me that whole approach is somewhere between a solution in search of a
problem and a "let's fix it and move on". Not something we need
explicitly carry in our CodingGuidelines forever.

The v1 of this series started with decreeing that nobody should be using
gendered language in commit messages. It seems that the discussion I
started that perhaps that was overly pedantic and unfriendly to people
struggling with English won out, so that's gone in recent revisions.

That's left only a handful of examples \b(?:she|he)\b in our docs, we
have outstanding patches to fix those, and draft guidelines (amended
above) to thoroughly lead documentation writers in other directions.

It just seems superfluous to me to insist on enumerating increasingly
obscure and disfavored alternatives to what we suggest as preferred
prose in our documentation. For example, we have around the same order
of magnitude of "one might" in Documentation/, I think we should
probably just fix that and move on, not forever have a guideline against
overly formal or "Shakespearean language" in the guidelines.

Ævar Arnfjörð Bjarmason wrote:

It just seems superfluous to me to insist on enumerating increasingly
obscure and disfavored alternatives to what we suggest as preferred
prose in our documentation. For example, we have around the same order
of magnitude of "one might" in Documentation/, I think we should
probably just fix that and move on, not forever have a guideline against
overly formal or "Shakespearean language" in the guidelines.

I also don't see much point in writing guidelines for something that
doesn't come up often, and hasn't come up in more than 15 years of life
of the project.

Does not smell like an issue.

-- 
Felipe Contreras

Junio C Hamano wrote:

-  - Removing the example person might make the sentence more
-    clear and efficient.  Instead of saying "The programmer
-    chooses between X and Y as she sees fit", it is clearer to
-    say "Valid choices are X and Y".
-
-  - If you need to talk about an example person, then try using
-    second-person to allow the reader to be that example.  For
-    example, "If you want X to happen, you'd pass option Y",
-    instead of "If the user wants X to happen, she'd ...").
-    Alternatively, replace the single example with more than one
-    person and use plural "they", such as "Interested readers
-    can read 'git log -p README' to learn the history in their
-    ample spare time" instead of "an interested reader" learning
-    in "his" spare time).
-
-  - If you absolutely need to refer to an example person that is
-    third-person singluar, you may resort to "singular they" (e.g.
-    "A contributor asks their upstream to pull from them").

Here is another escape hatch recommended by linguists before attempting
to use singular "they":

 - Use a generic alternative and count on the reader's common sense.
   Instead of saying "she made a mistake", say "a mistake was made".

-    Note
-    that this sounds ungrammatical and unnatural to those who
-    learned English as a second language in some parts of the
-    world, so should be avoided unless the earlier techniques
-    fail to improve the sentence.

For the nth time, it's not just foreign speakers:

https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they

+  - Prefer succinctness and matter-of-factly describing functionality
+    in the abstract.  E.g.
+
+     --short:: Emit output in the short-format.
+
+    and avoid something like these overly verbose alternatives:
+
+     --short:: Use this to emit output in the short-format.
+     --short:: You can use this to get output in the short-format.
+     --short:: A user who prefers shorter output could....
+     --short:: Should a person and/or program want shorter output, he
+               she/they/it can...
+
+    This practice often eliminates the need to involve human actors in
+    your description, but it is a good practice regardless of the
+    avoidance of gendered pronouns.
+
+  - When it becomes awkward to stick to this style, prefer "you" when
+    addressing the the hypothetical user, and possibly "we" when
+    discussing how the program might react to the user.  E.g.
+
+      You can use this option instead of --xyz, but we might remove
+      support for it in future versions.
+
+    while keeping in mind that you can probably be less verbose, e.g.
+
+      Use this instead of --xyz. This option might be removed in future
+      versions.
+
+  - If you still need to refer to an example person that is
+    third-person singular, you may resort to "singular they" to avoid
+    "he/she/him/her", e.g.
+
+      A contributor asks their upstream to pull from them.
+
+    Note that this sounds ungrammatical and unnatural to those who
+    learned English as a second language in some parts of the world.

These look OK to me, but I wonder why we have writing tips in *coding*
guidelines.

We are not writing a style manual, there's plenty of other tips writers
of documentation, commit messages and comments could use, why are we
only giving tips for gender pronouns?

Why don't we have a section on passive vs. active voice? How about
avoiding zombie nouns? Adjectives and adverbs? That vs. which? Who and
whom?

I don't think there's much value in trying to codify what is a good
sense of style while writing just for one particular non-issue.

Cheers.

-- 
Felipe Contreras

On 2021-06-16 at 19:54:20, Ævar Arnfjörð Bjarmason wrote:

The references to "gendered prounouns" etc. are gone, perhaps there's a
good reason to re-include them, but the point of "isn't that issue
solved by recommending an orthagonal approach?" is one of the many
things Stolee hasn't been addressing in the threads related to this
series.

I think I've addressed this.  Sometimes you can avoid referring to
people and therefore avoiding pronouns, and sometimes the prose reads
better if you talk about the user or actor.  Also, sometimes you need to
discuss a matter at length and using variety in your language is
desirable, so you may want to, for example, avoid continually using the
passive voice to discuss the topic.

I don't think it's fair to just say "don't refer to the user or other
humans if you'd need to use third-person pronouns" because I don't think
that's applicable in all cases.  I, for one, don't intend to write my
commit messages in that way because I think it will make them
substantially worse.  For example, I often discuss the behavior or
expectations of users when writing FAQ entries or other documentation
and sometimes we'll need to use pronouns.

I agree that in many cases we can effectively rephrase to avoid needing
to do this, but if we acknowledge that sometimes we will need to write
using third-person personal pronouns in some cases, it's worth
documenting what those should be.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

On Fri, Jun 18 2021, brian m. carlson wrote:

[[PGP Signed Part:Undecided]]
On 2021-06-16 at 19:54:20, Ævar Arnfjörð Bjarmason wrote:

quoted

The references to "gendered prounouns" etc. are gone, perhaps there's a
good reason to re-include them, but the point of "isn't that issue
solved by recommending an orthagonal approach?" is one of the many
things Stolee hasn't been addressing in the threads related to this
series.

I think I've addressed this.  Sometimes you can avoid referring to
people and therefore avoiding pronouns, and sometimes the prose reads
better if you talk about the user or actor.  Also, sometimes you need to
discuss a matter at length and using variety in your language is
desirable, so you may want to, for example, avoid continually using the
passive voice to discuss the topic.

I don't think it's fair to just say "don't refer to the user or other
humans if you'd need to use third-person pronouns" because I don't think
that's applicable in all cases.  I, for one, don't intend to write my
commit messages in that way because I think it will make them
substantially worse.

You won't have to. Reading this and your slightly earlier
[off-list ref] I think you've missed that
as of v2[1] of this series the proposal to is not to enforce this policy
on people's commit messages; so we're only talking about code comments
and documentation at this point.

[...]For example, I often discuss the behavior or
expectations of users when writing FAQ entries or other documentation
and sometimes we'll need to use pronouns.

I agree that in many cases we can effectively rephrase to avoid needing
to do this, but if we acknowledge that sometimes we will need to write
using third-person personal pronouns in some cases, it's worth
documenting what those should be.

I agree with you as a general matter that anything we come up with,
whether it's a prose guideline, coding style etc. won't cover all
cases.

But perhaps we disagree on whether that should be a goal of our
guidelines at all. I don't think it should. It shouldn't because it
simply won't work, the amount of guidelines we ask contributors to read
becomes a zero-sum game at some point.

Assuming that most contributors attempt to at least skim them we've
already reached that point. It's a trivial task to find recent
submissions of patches that violate one guideline or another.

So the criteria for inclusion shouldn't be whether we can think of cases
they apply to, but whether those cases are common enough to warrant
explicit mention, keeping in mind that any new addition will dilute
whatever advice we're already giving. Having gone over the number of
occurances we're fixing [2] I don't see how this qualifies.

As Stolee said upthread[3], referring to Documentation/CodingGuidelines
("[]" edits of what I understood him to mean are mine):

    [It's the document that we] should just be able to point to [say] "here
    is the decision we made"

I just don't think that should be a primary or secondary goal of that
document. We have e.g. this mailing list discussion to point to for some
decision we made.

The CodingGuidelines is what we're asking people to read when they've
e.g. found some data-eating bug in git and are about to send us a patch,
but before that we're asking them to go through a fuzzy checklist of
items checklist. It's already 20 pages in my browser if I were to try to
print it.

1. https://lore.kernel.org/git/pull.975.v2.git.1623246878.gitgitgadget@gmail.com/
2. https://lore.kernel.org/git/87o8c4wkn7.fsf@evledraar.gmail.com/
3. https://lore.kernel.org/git/5755690e-ef13-e12c-4b10-9cb303ae843a@gmail.com/

Ævar Arnfjörð Bjarmason wrote:

The CodingGuidelines is what we're asking people to read when they've
e.g. found some data-eating bug in git and are about to send us a patch,
but before that we're asking them to go through a fuzzy checklist of
items checklist. It's already 20 pages in my browser if I were to try to
print it.

Exactly.

Moreover, the point a guideline is on the name: guide. After reading it
developers should feel they are heading in the right direction, but they
won't know everything there is to know about git.git development, that
requires many years of practice, and mistakes.

More importantly than what it is, is what it's not: by-laws.

A developer that misses a point in the guidelines should not be
reprimended and sent to the brig. Instead she should merely be directed
to it.

Another thing it shouldn't be is a tool to win arguments. If two
developers argue about sentence spacing (one space vs. two spaces), even
if the whole community agrees two spaces is preferable--and thus one
developer "won" the argument--that still doesn't merit writing it down
to further rub it in.

Not everything belongs in the guideline; only the most salient tips that
guide newcomers in the right direction.

Cheers.

-- 
Felipe Contreras