| Message ID | xmqqk0lrtuh4.fsf_-_@gitster.g (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | CodingGuidelines: recommend gender-neutral description | expand |
On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano <gitster@pobox.com> 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. > 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.
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 <gitster@pobox.com> 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. I assume that it's supposed to read "guide us [to] avoid unnecessary [uses] of gendered description". > > > 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 <gitster@pobox.com> wrote: >> 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
Taylor Blau <me@ttaylorr.com> writes: > 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 <gitster@pobox.com> 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. > > I assume that it's supposed to read "guide us [to] avoid unnecessary > [uses] of gendered description". Thanks. Last-minute edit always screwes me up. >> > + 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. Yes, the language is living and drifting---and that is why it matters when and where you learned ;-)
Hi, On Thu, 15 Jul 2021, Derrick Stolee wrote: > On 7/15/2021 12:35 PM, Eric Sunshine wrote: > > On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano <gitster@pobox.com> wrote: > >> 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: > > On Thu, Jul 15, 2021 at 12:25 PM Junio C Hamano <gitster@pobox.com> wrote: > >> 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.
Taylor Blau wrote: > 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 <gitster@pobox.com> wrote: > > > 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
On 15/07/21 23.25, 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. > + 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.
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.