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

["Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com>]

From: Derrick Stolee <dstolee@microsoft.com>

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.

When choosing a gendered pronoun, that pronoun no longer applies to
nearly half of possible readers. Even if we alternated between "he/him"
and "she/her" perfectly evenly, we would still expect male and female
readers to experience an incorrect pronoun half the time. However, some
readers will not prescribe to either of these binary genders. Those
readers hence suffer an incorrect pronoun the entire time.

To make our documentation more inclusive, add recommendations to the
CodingGuidelines document. We can refer to this section when a
contributor submits a patch with a gendered pronoun and these
recommendations apply. The examples can assist in producing a new patch
with adjusted language.

As noted in the guidelines, removing an example person can make the
writing clearer and more concise. Other techniques such as singular
"you" and plural "they" are widely accepted ways to adjust the noun and
avoid gendered pronouns. Finally, an author can resort to singluar
"they" if absolutely necessary, but this can be difficult for readers
who learned English in a way that dictated "they" as always plural.

If we refer to a specific person, then using a gendered pronoun is
appropriate. There can also be other cases where it is inappropriate for
us to update the existing examples 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
  modifying the license this 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 <gitster@pobox.com>
Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 Documentation/CodingGuidelines | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index e3af089ecf26..0282f836548a 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -551,6 +551,34 @@ 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:
+
+  - 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.
+
  Every user-visible change should be reflected in the documentation.
  The same general rule as for code applies -- imitate the existing
  conventions.
-- 
gitgitgadget