[PATCH] CodingGuidelines: recommend gender-neutral description

Ævar Arnfjörð Bjarmason [off-list ref] writes:

quoted

I've said before and will repeat here that the draft in your
SQUASH??? commit looks like a good compromise to me. It can
replace the other commit in this branch.

Just doing that would leave the commit message that says "change X",
when we're now changing X, Y and Z. I.e.  With the squash it changes
from narrowly focusing on the pronoun question into a start of a general
prose and style guide for our documentation.

Yeah, that is a good point.  Perhaps like this?

-- >8 ---- >8 ---- >8 -- cut here -- >8 ---- >8 ---- >8 --

Technical writing seeks to convey information with minimal
friction. One way that a reader can experience friction is if they
encounter a description of "a user" that is later simplified using a
gendered pronoun. If the reader does not consider that pronoun to
apply to them, then they can experience cognitive dissonance that
removes focus from the information.

Give some basic tips to guide us avoid unnecessary of gendered
description.

Using a gendered pronoun is appropriate when referring to a specific
person.

There are acceptable existing uses of gendered pronouns within the
Git codebase, such as:

* 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 avoid using pronouns.

* References to fictional people with clear genders (e.g. Alice and
  Bob).

* Sample text used in test cases (e.g t3702, t6432).

* The official text of the GPL license contains uses of "he or she",
  but using singular "they" (or modifying the text in some other
  way) is not within the scope of the Git project.

* Literal email messages in Documentation/howto/ should not be edited
  for grammatical concerns such as this, unless we update the entire
  document to fit the standard documentation format. If such an effort is
  taken on, then the authorship would change and no longer refer to the
  exact mail message.

* External projects consumed in contrib/ should not deviate solely for
  style reasons. Recommended edits should be contributed to those
  projects directly.

Other cases within the Git project were cleaned up by the previous
changes.

Co-authored-by: Junio C Hamano [off-list ref]
Signed-off-by: Derrick Stolee <redacted>
Signed-off-by: Junio C Hamano <redacted>
---
 Documentation/CodingGuidelines | 43 ++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 45465bc0c9..476b840d30 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines

@@ -541,6 +541,49 @@ Writing Documentation:
  documentation, please see the documentation-related advice in the
  Documentation/SubmittingPatches file).
 
+ In order to ensure the documentation is inclusive, avoid assuming
+ that an unspecified example person is male or female, and think
+ twice before using "he", "him", "she", or "her".  Here are some
+ tips to avoid use of gendered pronouns:
+
+  - 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
  conventions.

-- 
2.32.0-443-g7e6d7322bf

On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano [off-list ref] wrote:

Technical writing seeks to convey information with minimal
friction. One way that a reader can experience friction is if they
encounter a description of "a user" that is later simplified using a
gendered pronoun. If the reader does not consider that pronoun to
apply to them, then they can experience cognitive dissonance that
removes focus from the information.

Give some basic tips to guide us avoid unnecessary of gendered
description.

Some words seem to be missing from this sentence.

It also sounds ungrammatical and unnatural to this native English speaker.

On Thu, Jul 15, 2021 at 12:35:30PM -0400, Eric Sunshine wrote:

On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano [off-list ref] wrote:

quoted

Technical writing seeks to convey information with minimal
friction. One way that a reader can experience friction is if they
encounter a description of "a user" that is later simplified using a
gendered pronoun. If the reader does not consider that pronoun to
apply to them, then they can experience cognitive dissonance that
removes focus from the information.

Give some basic tips to guide us avoid unnecessary of gendered
description.

Some words seem to be missing from this sentence.

I assume that it's supposed to read "guide us [to] avoid unnecessary
[uses] of gendered description".

quoted

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines

@@ -541,6 +541,49 @@ Writing Documentation:
+      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.

It also sounds ungrammatical and unnatural to this native English speaker.

Apologies if this suggestion has been made earlier in the thread, but
this article

    https://apastyle.apa.org/style-grammar-guidelines/grammar/singular-they

document from the APA's style guide helps convince me that this is
grammatical.

Thanks,
Taylor

On 7/15/2021 12:35 PM, Eric Sunshine wrote:

On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano [off-list ref] wrote:

quoted

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines

@@ -541,6 +541,49 @@ Writing Documentation:
+      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.

It also sounds ungrammatical and unnatural to this native English speaker.

A way to adapt this idea more generally would be to pull a phrase
from my commit message in v3:

  Note that this sounds ungrammatical and unnatural to readers
  who learned English in a way that dictated "they" as always plural.

Learning English as a second language is one example of how one could
find it ungrammatical. We could call it out explicitly:

  Note that this sounds ungrammatical and unnatural to readers
  who learned English in a way that dictated "they" as always plural,
  especially those who learned English as a second language.

Thanks,
-Stolee

Hi,

On Thu, 15 Jul 2021, Derrick Stolee wrote:

On 7/15/2021 12:35 PM, Eric Sunshine wrote:

quoted

On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano [off-list ref] wrote:

quoted

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines

@@ -541,6 +541,49 @@ Writing Documentation:
+      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.

It also sounds ungrammatical and unnatural to this native English speaker.

A way to adapt this idea more generally would be to pull a phrase
from my commit message in v3:

  Note that this sounds ungrammatical and unnatural to readers
  who learned English in a way that dictated "they" as always plural.

Learning English as a second language is one example of how one could
find it ungrammatical. We could call it out explicitly:

  Note that this sounds ungrammatical and unnatural to readers
  who learned English in a way that dictated "they" as always plural,
  especially those who learned English as a second language.

I like the latter form.

Ciao,
Dscho "who will never stop learning English because learning never ends"

Derrick Stolee wrote:

On 7/15/2021 12:35 PM, Eric Sunshine wrote:

quoted

On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano [off-list ref] wrote:

quoted

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines

@@ -541,6 +541,49 @@ Writing Documentation:
+      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.

It also sounds ungrammatical and unnatural to this native English speaker.

A way to adapt this idea more generally would be to pull a phrase
from my commit message in v3:

  Note that this sounds ungrammatical and unnatural to readers
  who learned English in a way that dictated "they" as always plural.

Learning English as a second language is one example of how one could
find it ungrammatical. We could call it out explicitly:

  Note that this sounds ungrammatical and unnatural to readers
  who learned English in a way that dictated "they" as always plural,
  especially those who learned English as a second language.

This is loaded language. You are inserting your opinion into the text.

Don't. The guidelines are not a place to win arguments.

  Note that this sounds ungrammatical and unnatural to some people.

And it sounds ungrammatical because it *is* ungramatical, not only to
native English speakers, but professional linguists.

-- 
Felipe Contreras

Taylor Blau wrote:

On Thu, Jul 15, 2021 at 12:35:30PM -0400, Eric Sunshine wrote:

quoted

On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano [off-list ref] wrote:

quoted

quoted

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines

@@ -541,6 +541,49 @@ Writing Documentation:
+      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.

It also sounds ungrammatical and unnatural to this native English speaker.

Apologies if this suggestion has been made earlier in the thread, but
this article

    https://apastyle.apa.org/style-grammar-guidelines/grammar/singular-they

document from the APA's style guide helps convince me that this is
grammatical.

That's the opinion of one organization (biased in my opinion). Other
organizations disagree:

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

-- 
Felipe Contreras

On 15/07/21 23.25, Junio C Hamano wrote:

Addendum: For grammatical correctness (for ESL people), proper, plural they can be used. So the last example can be rewritten as:

  Contributors ask their upstream to pull from their repository.

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