From: Derrick Stolee <dstolee@xxxxxxxxxxxxx> 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@xxxxxxxxx> Signed-off-by: Derrick Stolee <dstolee@xxxxxxxxxxxxx> --- 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
