* [PATCH] docs: update coding guidelines to be more inclusive @ 2022-02-16 16:34 Merlin (they/them) via GitGitGadget 2022-02-16 22:12 ` Junio C Hamano 0 siblings, 1 reply; 6+ messages in thread From: Merlin (they/them) via GitGitGadget @ 2022-02-16 16:34 UTC (permalink / raw) To: git; +Cc: Merlin (they/them), Merlin (they/them) Patterson From: "Merlin (they/them) Patterson" <merlinpatt+githubgit@gmail.com> These changes make this documentation more inclusive. Using "male" and "female" as examples of gender is unnecessary. The use of "it" shouldn't be used to refer to people even in an example of what not to use. People are never "it"s. There's no need to specify a person or group of people that learned "they" is only plural. Signed-off-by: Merlin (they/them) Patterson <merlinpatt+githubgit@gmail.com> --- docs: Update CodingGuidelines to be more inclusive These changes make this documentation more inclusive. * Using "male" and "female" as examples of gender is unnecessary. * The use of "it" shouldn't be used to refer to people even in an example of what not to use. People are never "it"s. * There's no need to specify a person or group of people that learned "they" is only plural. Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1070%2Fmerlinpatt%2Fpatch-1-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1070/merlinpatt/patch-1-v1 Pull-Request: https://github.com/git/git/pull/1070 Documentation/CodingGuidelines | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 711cb9171e0..ffd7fa9c0f4 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -552,9 +552,9 @@ Writing Documentation: 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: + the gender of an example person, and think twice before using + "he", "him", "she", or "her". Here are some tips to avoid the use + of gendered pronouns: - Prefer succinctness and matter-of-factly describing functionality in the abstract. E.g. @@ -566,8 +566,8 @@ Writing Documentation: --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... + --short:: Should a person and/or program want shorter output, + he/she/they can... This practice often eliminates the need to involve human actors in your description, but it is a good practice regardless of the @@ -586,15 +586,13 @@ Writing Documentation: versions. - If you still need to refer to an example person that is - third-person singular, you may resort to "singular they" to avoid + 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. + learned that "they" is only used for third-person plural. Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing base-commit: 225bc32a989d7a22fa6addafd4ce7dcd04675dbf -- gitgitgadget ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: update coding guidelines to be more inclusive 2022-02-16 16:34 [PATCH] docs: update coding guidelines to be more inclusive Merlin (they/them) via GitGitGadget @ 2022-02-16 22:12 ` Junio C Hamano 2022-02-17 10:02 ` Ævar Arnfjörð Bjarmason 0 siblings, 1 reply; 6+ messages in thread From: Junio C Hamano @ 2022-02-16 22:12 UTC (permalink / raw) To: Merlin (they/them) via GitGitGadget; +Cc: git, Merlin (they/them) "Merlin (they/them) via GitGitGadget" <gitgitgadget@gmail.com> writes: > These changes make this documentation more inclusive. I am not sure about this claim, though. > * Using "male" and "female" as examples of gender is unnecessary. It feels somewhat more excluding for those of us who are non-native speakers to use a heavier-weight word "gender". After all, it warns against writing "he", "him", "she" or "her"---the reason why we warn against the first two is because the author has to implicitly assume the person in question is "male". Similarly the latter two needs to assume "female". These two words, "male" and "female", are both easier to understand to even non-native speakers like us, and at the same time quite in line with the suggestion being offered. Maybe the motivation behind this change is a misunderstanding that somehow the original of what this patch touches says that "male" and "female" are the only two possible values of "gender", but I cannot read it that way even when I squint my eyes. > * The use of "it" shouldn't be used to refer to people even in an > example of what not to use. People are never "it"s. People are never "it", but I do not think that is relevant. Reading the original of what this patch touches, the subject is either a person or a program, and for program, referring to "it" would be perfectly sensible, no? > * There's no need to specify a person or group of people that learned > "they" is only plural. Again, this change assumes/requires too much knowledge of the language, which is more excluding for non-natives who may think there is only one kind of the English language taught everywhere in the world uniformly unless told explicitly. If you are familiar, there may be "no need", but does it actively hurt those of you who are familiar if the explanation gives such an example? Removing it may actively hurt those who did learn English as a second language. So, I can applaud for the desire to be inclusive, but I am not sure if the patch succeeds in doing so. Thanks. > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1070%2Fmerlinpatt%2Fpatch-1-v1 > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1070/merlinpatt/patch-1-v1 > Pull-Request: https://github.com/git/git/pull/1070 > > Documentation/CodingGuidelines | 16 +++++++--------- > 1 file changed, 7 insertions(+), 9 deletions(-) > > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 711cb9171e0..ffd7fa9c0f4 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -552,9 +552,9 @@ Writing Documentation: > 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: > + the gender of an example person, and think twice before using > + "he", "him", "she", or "her". Here are some tips to avoid the use > + of gendered pronouns: > > - Prefer succinctness and matter-of-factly describing functionality > in the abstract. E.g. > @@ -566,8 +566,8 @@ Writing Documentation: > --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... > + --short:: Should a person and/or program want shorter output, > + he/she/they can... > > This practice often eliminates the need to involve human actors in > your description, but it is a good practice regardless of the > @@ -586,15 +586,13 @@ Writing Documentation: > versions. > > - If you still need to refer to an example person that is > - third-person singular, you may resort to "singular they" to avoid > + 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. > + learned that "they" is only used for third-person plural. > > Every user-visible change should be reflected in the documentation. > The same general rule as for code applies -- imitate the existing > > base-commit: 225bc32a989d7a22fa6addafd4ce7dcd04675dbf ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: update coding guidelines to be more inclusive 2022-02-16 22:12 ` Junio C Hamano @ 2022-02-17 10:02 ` Ævar Arnfjörð Bjarmason 2022-02-18 3:02 ` Junio C Hamano 0 siblings, 1 reply; 6+ messages in thread From: Ævar Arnfjörð Bjarmason @ 2022-02-17 10:02 UTC (permalink / raw) To: Junio C Hamano Cc: Merlin (they/them) via GitGitGadget, git, Merlin (they/them), brian m. carlson On Wed, Feb 16 2022, Junio C Hamano wrote: > "Merlin (they/them) via GitGitGadget" <gitgitgadget@gmail.com> > writes: > >> These changes make this documentation more inclusive. > > I am not sure about this claim, though. > >> * Using "male" and "female" as examples of gender is unnecessary. > > It feels somewhat more excluding for those of us who are non-native > speakers to use a heavier-weight word "gender". After all, it warns > against writing "he", "him", "she" or "her"---the reason why we warn > against the first two is because the author has to implicitly assume > the person in question is "male". Similarly the latter two needs to > assume "female". These two words, "male" and "female", are both > easier to understand to even non-native speakers like us, and at the > same time quite in line with the suggestion being offered. > > Maybe the motivation behind this change is a misunderstanding that > somehow the original of what this patch touches says that "male" and > "female" are the only two possible values of "gender", but I cannot > read it that way even when I squint my eyes. Isn't that exactly what it's saying? I.e. for the purposes of the English used in our documentation there's two grammatical genders "he ran the program", "she ran the program" and gender-neutral "it/they ran the program". >> * The use of "it" shouldn't be used to refer to people even in an >> example of what not to use. People are never "it"s. > > People are never "it", but I do not think that is relevant. Reading > the original of what this patch touches, the subject is either a > person or a program, and for program, referring to "it" would be > perfectly sensible, no? Yes, as the person who wrote this originally (in https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/) that's what I was going for. It's referring to describing a program as "it". >> * There's no need to specify a person or group of people that learned >> "they" is only plural. > > Again, this change assumes/requires too much knowledge of the > language, which is more excluding for non-natives who may think > there is only one kind of the English language taught everywhere in > the world uniformly unless told explicitly. If you are familiar, > there may be "no need", but does it actively hurt those of you who > are familiar if the explanation gives such an example? Removing it > may actively hurt those who did learn English as a second language. > > So, I can applaud for the desire to be inclusive, but I am not sure > if the patch succeeds in doing so. Per what I noted the last time this was discussed I think that we should mostly drop this section entirely in favor of some guidelines describing how to actually write the docs that we do write, not what not to do in the rare/nonexistent cases of using grammatical genders: https://lore.kernel.org/git/87pmwt1dz3.fsf@evledraar.gmail.com/ brian's follow-up provides a good example of what we try to aim for: https://lore.kernel.org/git/YMKTARn368Qzsqc2@camp.crustytoothpaste.net/ The thing that's uninclusive here is asking non-native speakers of English who are trying to contribute to this project to grasp some fairly advanced linguistic concepts. I think it's fair to say that the use of "they" as a personal pronoun is fairly new/novel English language as it's commonly understood. I.e. if you talk to any person who's not a native-level speaker of English it's a fair assumption that their introductory textbook didn't cover it. As noted in those old threads I'm entirely sympathetic to the goal of avoiding gendered language if it's a thing that matters for some readers, which clearly it does[1]. It just demonstrably isn't relevant to our documentation in practice, so this whole advice ends up being a bridge to nowhere. It's comparable to us carrying C++ coding guide lines in-tree. 1. To be fair, I do find it a bit odd, but then again I'm a non-native speaker, and I'm unable to refer to even the monitor, keyboard and laptop I'm using to type this in my in my native language without assigning the three (different!) genders. I can assure the concerned native English speakers that by all accounts Iceland's got a rather good track record when it comes to gender equlity despite that :) ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: update coding guidelines to be more inclusive 2022-02-17 10:02 ` Ævar Arnfjörð Bjarmason @ 2022-02-18 3:02 ` Junio C Hamano [not found] ` <CAFZ26y3re+fJapXzLOpf73F-ECXhg2sCoBtm_=VUFy5nbN2UVQ@mail.gmail.com> 0 siblings, 1 reply; 6+ messages in thread From: Junio C Hamano @ 2022-02-18 3:02 UTC (permalink / raw) To: Ævar Arnfjörð Bjarmason Cc: Merlin (they/them) via GitGitGadget, git, Merlin (they/them), brian m. carlson Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: >> Maybe the motivation behind this change is a misunderstanding that >> somehow the original of what this patch touches says that "male" and >> "female" are the only two possible values of "gender", but I cannot >> read it that way even when I squint my eyes. > > Isn't that exactly what it's saying? I.e. for the purposes of the > English used in our documentation there's two grammatical genders "he > ran the program", "she ran the program" and gender-neutral "it/they ran > the program". Yes, for the purpose of the language, there are only two grammatical genders, "male", "female" (and "thing"). But my point was that the documentation was not making any non-technical value judgement like "genders outside these two are forbidden". What I found problematic with the rewrite is that by moving from more concrete examples ("avoid 'he' and do not assume 'male'") to a more abstract wording ("avoid gendered pronouns"), it would burden non-natives disproportionally more, and I do not see a clear benefit to offset the downside. I do not think it adds anything to discussion to repeat what was already said, so I'll refrain from commenting on the other two changes in the patch, but they posed the same problem to me. I cannot convincingly answer with "yes" to the question "does it overall help inclusiveness? really? how?" ^ permalink raw reply [flat|nested] 6+ messages in thread
[parent not found: <CAFZ26y3re+fJapXzLOpf73F-ECXhg2sCoBtm_=VUFy5nbN2UVQ@mail.gmail.com>]
* Re: [PATCH] docs: update coding guidelines to be more inclusive [not found] ` <CAFZ26y3re+fJapXzLOpf73F-ECXhg2sCoBtm_=VUFy5nbN2UVQ@mail.gmail.com> @ 2022-02-18 23:18 ` Ævar Arnfjörð Bjarmason 2022-02-20 21:23 ` brian m. carlson 0 siblings, 1 reply; 6+ messages in thread From: Ævar Arnfjörð Bjarmason @ 2022-02-18 23:18 UTC (permalink / raw) To: Merlin (they / them) Patterson Cc: Junio C Hamano, Merlin (they/them) via GitGitGadget, git, Merlin (they/them), brian m. carlson [You need to configure your E-Mail client to stop sending HTML E-Mail to the Git mailing list. It's all being rejected by kernel.org. See e.g. https://lore.kernel.org/git/pull.1070.git.git.1645029267415.gitgitgadget@gmail.com/ where only your initial posting is visible, but not your replies. It's also good etiquette on the ML not to top-post your replies, but to reply inline. Except perhaps when not in reply to specific points, such as this part of my reply :) For other ML readers who weren't directly CC'd I'm quoting your reply to my <220217.86a6epiyii.gmgdl@evledraar.gmail.com> here in full (sent Thu, 17 Feb 2022 10:51:35 -0500 as<CAFZ26y0VPVyAjq4Fh+CQRMu=J9rYZG6PQWpHFiWRKZJFb3aAEw@mail.gmail.com>):] On Thu, Feb 17 2022, Merlin (they / them) Patterson wrote: > Removing "male" and "female" allows for a broader statement of "don't assume any gender and always keep it gender neutral". > What if I change it to remove the bit about the example person altogether? > > * In order to ensure the documentation is inclusive, think twice before using > > The example given starts off with people and has he/she/they/it in it. This ties "it" to he/she/they, making it sound like "it" also refers to a person. > I don't think the program part makes sense as part of that example anyway. How about that be separated into its own example? > > * --short:: Should a person want shorter output, he/she/they can... > * --short:: Should a program want shorter output, it can... Yes, as the person who wrote this whole thing initially I don't really stand by it, i.e. it was edited from a throwaway comment of mine. For what it's worth I don't really find the he/it person/program of it ambiguous, but what do I know?:) Aside from that referring to an "it" in the context of our documentation *is* something we need to do. Git the program is often (usually?) invoked by other programs, not directly by human agency. In any case, what do you think about this instead: diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index c37c43186ea..2bcb748aaa3 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -600,12 +600,6 @@ Writing Documentation: --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 @@ -619,16 +613,10 @@ Writing Documentation: 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. + - Referring to users as a cast of characters (Alice, Bob etc.) or in + the third-person singular is too obscure to worry about for the + purposes of this style guide. Search the mailing list archive for + "third-person singular" for more. Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing > As for the part about removing "those who learn English as a second language in some parts of the world.", I stand by that. > Even native English speakers also believe that "they" is only a third person plural. That's not restricted to non-native English speakers. > Also, it's weird to give an example for this. Either a person learned that "they" can be both singular and plural or they didn't. Whether they learned English as a second or other language > is irrelevant. > How does providing an example benefit anyone? ... On Thu, Feb 17 2022, Merlin (they / them) Patterson wrote: > "It" and "they" shouldn't be grouped together. Examples using "it" must be separated from examples using "they". This prevents confusion around which word refers to what. And it ensures that > a person is not thought of as an "it". > > This is why I suggested that I could split the example so "it" clearly refers to "the program" and can't be confused as referring to a person. > > As for removing the example about non-native English speakers, I gave my reasoning but I'll give it again. The example doesn't help anyone. A lot of native English speakers also think "they" > can only be plural.[...] I think this came about because of a previous discussion that you'll find in the list archive where some native speakers were maintaining that "they" in this context was widely accepted usage because it had made it into some style guides single-digit years ago. I.e. this was a perhaps flawed attempt to say something like "this phrasing sounds weird, but it's actually correct". As someone who speaks at least 4 languages regularly with levels of proficiency ranging from native to something that sound as though I'm trying to butcher the language, I can assure you that advice like that *is* really useful to a non-native speaker. I.e. whatever you or anyone else thinks about this usage of "they" it *is* relatively obscure usage of English. I'd even bet that for some readers of this document it's the first time they've ever seen it. So just like the pronoun "thy", it's useful to add a small explanation that it's in fact not a typo or something. > Explicitly calling out non-native English speakers as making this > mistake can have an alienating effect. I realize I'm just shouting into the ether from my little soap box at this point, but the alienating thing to non-native speakers isn't that we might be told that our English isn't as good as that of non-native speakers. It's okey, really. We know. It's the opposite, it's that a lot of people aren't assuming that others who who want to participate in this project might have 1/10th of their reading comprehension and reading speed when it comes to dense technical documentation like this. Because if they did we might have less of the "read this before you contribute" documentation, or more narrowlry tailor it to practical issues contributors are likely to encounter. Which is why I've been maintaining (and still do) that removing most of this is the right thing to do. It's clearly something anyone maintaining our documentation is unlikely to encounter or have to worry about, and therefore doesn't at all belong as a hurdle we put in the way of any new contributor in the form of documentation we advise them to read before they submit their first patch. ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: update coding guidelines to be more inclusive 2022-02-18 23:18 ` Ævar Arnfjörð Bjarmason @ 2022-02-20 21:23 ` brian m. carlson 0 siblings, 0 replies; 6+ messages in thread From: brian m. carlson @ 2022-02-20 21:23 UTC (permalink / raw) To: Ævar Arnfjörð Bjarmason Cc: Merlin (they / them) Patterson, Junio C Hamano, Merlin (they/them) via GitGitGadget, git, Merlin (they/them) [-- Attachment #1: Type: text/plain, Size: 3881 bytes --] On 2022-02-18 at 23:18:35, Ævar Arnfjörð Bjarmason wrote: > I think this came about because of a previous discussion that you'll > find in the list archive where some native speakers were maintaining > that "they" in this context was widely accepted usage because it had > made it into some style guides single-digit years ago. Singular they has been in common use for centuries. It became less common for many years because prescriptivists proposed using "he" to refer to people of all genders, which was in common use for a long time, until it was widely criticized as being sexist (and also, at times, sounding bizarre). "He or she" was then used in formal writing, but that was also criticized as not being inclusive as well as being wordy and awkward. During this entire time, singular they has remained in common use in speech and informal writing and is widely recognized as part of the English language. It's true that it is only now becoming more acceptable in formal writing, but it is well known and commonly used in English as a whole and has been for a long time. I will also freely admit that for people who have learned English as a second language sometime in the past, this would probably not have been covered in the textbook. As I continue to use Spanish, I learn things about the language and how it's used today that differ from what I learned when I started learning it formally over two decades ago, and that's okay. Language evolves and as speakers of a second or third language, we'll have to evolve with it. > I.e. this was a perhaps flawed attempt to say something like "this > phrasing sounds weird, but it's actually correct". > > As someone who speaks at least 4 languages regularly with levels of > proficiency ranging from native to something that sound as though I'm > trying to butcher the language, I can assure you that advice like that > *is* really useful to a non-native speaker. I agree, this context would be helpful. Maybe, if we retain this, we can just explicitly say, "Even though some non-native speakers may find the use of singular they unusual, it is in fact common in English and preferred in our documentation." > I.e. whatever you or anyone else thinks about this usage of "they" it > *is* relatively obscure usage of English. I'd even bet that for some > readers of this document it's the first time they've ever seen it. It is simply not the case that this is obscure. As I've said in the past, singular they, in the sense of referring to a single person whose gender is unknown or irrelevant, has been in use since the 14th century and has been used by William Shakespeare, Lord Byron, and Jane Austen. It is routinely used for this purpose by fluent non-native speakers as well (I have noted colleagues doing this). I will admit that using they as the pronoun for a person whose gender is known and who has explicitly requested the use of this pronoun is much more recent, which probably dates to the mid 20th century (albeit at a much lower frequency than today), but this is not the context in which we are using the pronoun in our documentation. It may be that for some readers it is the first time they've seen it, but it will be far from the last if they continue to read English. Understanding the main idea of a technical document in one's specialized field (e.g., the Git documentation) is part of the CEFR B2 level, and at that point, I'd expect the reader to have read numerous news articles and online documents where this usage is common or becoming so. As to your suggestion to this effect, I should point out that I'm fine with removing this text from the documentation, as you suggested, provided we can stop having extended debates about it on the list. -- brian m. carlson (he/him or they/them) Toronto, Ontario, CA [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 262 bytes --] ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2022-02-20 21:26 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-02-16 16:34 [PATCH] docs: update coding guidelines to be more inclusive Merlin (they/them) via GitGitGadget 2022-02-16 22:12 ` Junio C Hamano 2022-02-17 10:02 ` Ævar Arnfjörð Bjarmason 2022-02-18 3:02 ` Junio C Hamano [not found] ` <CAFZ26y3re+fJapXzLOpf73F-ECXhg2sCoBtm_=VUFy5nbN2UVQ@mail.gmail.com> 2022-02-18 23:18 ` Ævar Arnfjörð Bjarmason 2022-02-20 21:23 ` brian m. carlson
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).