[v2] CodingGuidelines: recommend gender-neutral description

Commit Message

Junio C Hamano July 16, 2021, 6:41 p.m. UTC

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 uses 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 <[e-mail]>
Signed-off-by: Derrick Stolee <[e-mail]>
Signed-off-by: Junio C Hamano <[e-mail]>
---

 The only change relative to the previous one is that this
 explicitly calls out that some are taught that 'they' is only used
 for third-person plural.  As we already say that some foreigners
 find it ungrammatical and unnatural to use 'they', I actually do
 not think it is necessary, but I'd prefer not to leave easy loose
 end hanging untied, so let's close this round and let others polish
 on top if they wanted to after the dust settls.

 Documentation/CodingGuidelines | 45 ++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

Comments

Derrick Stolee July 16, 2021, 7:05 p.m. UTC | #1

On 7/16/2021 2:41 PM, Junio C Hamano wrote:
>  The only change relative to the previous one is that this
>  explicitly calls out that some are taught that 'they' is only used
>  for third-person plural.  As we already say that some foreigners
>  find it ungrammatical and unnatural to use 'they', I actually do
>  not think it is necessary, but I'd prefer not to leave easy loose
>  end hanging untied, so let's close this round and let others polish
>  on top if they wanted to after the dust settls.
...
> +    Note that this sounds ungrammatical and unnatural to those who
> +    learned that "they" is only used for third-person plural, e.g.
> +    those who learn English as a second language in some parts of the
> +    world.

Perfect. Thank you.

-Stolee

Ævar Arnfjörð Bjarmason July 16, 2021, 7:11 p.m. UTC | #2

On Fri, Jul 16 2021, Junio C Hamano 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 uses 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 <[e-mail]>
> Signed-off-by: Derrick Stolee <[e-mail]>
> Signed-off-by: Junio C Hamano <[e-mail]>

On the topic of co-authors & SOB this text does look quite familiar:
https://lore.kernel.org/git/[e-mail]/ :)

>  The only change relative to the previous one is that this
>  explicitly calls out that some are taught that 'they' is only used
>  for third-person plural.  As we already say that some foreigners
>  find it ungrammatical and unnatural to use 'they', I actually do
>  not think it is necessary[...]

The proposed commit message...

> + 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:

Applies to this:

> +  - 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...

But this.

> +    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.

Not this.

> +  - 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.

But this.

> +  - 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 that "they" is only used for third-person plural, e.g.
> +    those who learn English as a second language in some parts of the
> +    world.
> +

And not this, have, respectively, nothing to do and mostly everything to
do with the commit message.

IOW I don't think we should conflate a section on general style in our
common patterns/issues in our docs and one that at the end state of this
series is discussing the already-rare-now-nonexistent pattern that the
proposed policy is trying to prevent ever making it in-tree again, or to
put the entirety of a general style guide under the equivalent of "how
to avoid gendered pronouns".

IOW to have this instead (this is mostly a mere moving of your proposed
version):

== BEGIN==

General style points for our documentation

 - 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...

 - 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.

Discussing beings in our documentation:

  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:

  The practice of avoiding verbosity discussed above often eliminates
  the need to involve human actors in your description.

 - 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 that "they" is only used for third-person plural, e.g.
   those who learn English as a second language in some parts of the
   world.

== END == 

I'd be happy to re-arrange this, if I could only get the submitter of
the series to respond to my E-Mails...

Snipping around above:

> , but I'd prefer not to leave easy loose
>  end hanging untied, so let's close this round and let others polish
>  on top if they wanted to after the dust settls.

Sure, but as someone who'll probably want to patch the first part of
this at one point or another, it's going to be rather weird to cover
e.g. how we prefer to quote options or refer to things in
errors/warnings or whatever all under a section that says all of the
below is in the service of the avoidance of gender pronouns.

Whereas it's mostly the case that our docs are just following a style
established in common OS-level docs at a time when I daresay this topic
wasn't part of the zeitgeist.

Junio C Hamano July 16, 2021, 7:50 p.m. UTC | #3

Ævar Arnfjörð Bjarmason <[e-mail]> writes:

> I'd be happy to re-arrange this, if I could only get the submitter of
> the series to respond to my E-Mails...

I'll do this only once to add missing but intended recipient to the
to: line; you are both adults, don't assume malice but instead good
intentions and talk to each other.

Felipe Contreras July 16, 2021, 9:14 p.m. UTC | #4

Junio C Hamano wrote:
> Ævar Arnfjörð Bjarmason <[e-mail]> writes:
> 
> > I'd be happy to re-arrange this, if I could only get the submitter of
> > the series to respond to my E-Mails...
> 
> I'll do this only once to add missing but intended recipient to the
> to: line; you are both adults, don't assume malice but instead good
> intentions and talk to each other.

That's ironic, given that you don't talk to me, which is BTW against the
code of conduct:

 * Being respectful of differing opinions, viewpoints, and experiences

You clearly do not respect my differing opinions.

It's not about being adults, it's about being *tolerant* about other
people's opinions (I still insist "respect" is the wrong term).

Cheers.

Patch

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 45465bc0c9..b1f199b1fe 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -541,6 +541,51 @@  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 that "they" is only used for third-person plural, e.g.
+    those who learn 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.