{"thread":{"id":"57426","subject":"[PATCH] docs: update coding guidelines to be more inclusive","startedAt":"2022-02-16T16:34:34Z","lastAt":"2022-02-20T21:23:40Z","messageCount":6,"participants":["Merlin (they/them) via GitGitGadget","Junio C Hamano","Ævar Arnfjörð Bjarmason","brian m. carlson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"448610","messageId":"pull.1070.git.git.1645029267415.gitgitgadget@gmail.com","threadId":"57426","inReplyTo":null,"subject":"[PATCH] docs: update coding guidelines to be more inclusive","fromName":"Merlin (they/them) via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-02-16T16:34:27Z","receivedAt":"2022-02-16T16:34:34Z","isPatch":true,"sender":{"key":"name:Merlin (they/them)","avatar":null},"body":"From: \"Merlin (they/them) Patterson\" \n\nThese changes make this documentation more inclusive.\nUsing \"male\" and \"female\" as examples of gender is unnecessary.\nThe use of \"it\" shouldn't be used to refer to people even in an\n example of what not to use. People are never \"it\"s.\nThere's no need to specify a person or group of people that\n learned \"they\" is only plural.\n\nSigned-off-by: Merlin (they/them) Patterson \n---\n docs: Update CodingGuidelines to be more inclusive\n \n These changes make this documentation more inclusive.\n \n * Using \"male\" and \"female\" as examples of gender is unnecessary.\n * The use of \"it\" shouldn't be used to refer to people even in an\n example of what not to use. People are never \"it\"s.\n * There's no need to specify a person or group of people that learned\n \"they\" is only plural.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1070%2Fmerlinpatt%2Fpatch-1-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1070/merlinpatt/patch-1-v1\nPull-Request: https://github.com/git/git/pull/1070\n\n Documentation/CodingGuidelines | 16 +++++++---------\n 1 file changed, 7 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 711cb9171e0..ffd7fa9c0f4 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -552,9 +552,9 @@ Writing Documentation:\n Documentation/SubmittingPatches file).\n \n In order to ensure the documentation is inclusive, avoid assuming\n- that an unspecified example person is male or female, and think\n- twice before using \"he\", \"him\", \"she\", or \"her\". Here are some\n- tips to avoid use of gendered pronouns:\n+ the gender of an example person, and think twice before using\n+ \"he\", \"him\", \"she\", or \"her\". Here are some tips to avoid the use\n+ of gendered pronouns:\n \n - Prefer succinctness and matter-of-factly describing functionality\n in the abstract. E.g.\n@@ -566,8 +566,8 @@ Writing Documentation:\n --short:: Use this to emit output in the short-format.\n --short:: You can use this to get output in the short-format.\n --short:: A user who prefers shorter output could....\n- --short:: Should a person and/or program want shorter output, he\n- she/they/it can...\n+ --short:: Should a person and/or program want shorter output,\n+ he/she/they can...\n \n This practice often eliminates the need to involve human actors in\n your description, but it is a good practice regardless of the\n@@ -586,15 +586,13 @@ Writing Documentation:\n versions.\n \n - If you still need to refer to an example person that is\n- third-person singular, you may resort to \"singular they\" to avoid\n+ third-person singular, you may resort to singular \"they\" to avoid\n \"he/she/him/her\", e.g.\n \n A contributor asks their upstream to pull from them.\n \n Note that this sounds ungrammatical and unnatural to those who\n- learned that \"they\" is only used for third-person plural, e.g.\n- those who learn English as a second language in some parts of the\n- world.\n+ learned that \"they\" is only used for third-person plural.\n \n Every user-visible change should be reflected in the documentation.\n The same general rule as for code applies -- imitate the existing\n\nbase-commit: 225bc32a989d7a22fa6addafd4ce7dcd04675dbf\n-- \ngitgitgadget\n"},{"id":"448643","messageId":"xmqq4k4ycvgb.fsf@gitster.g","threadId":"57426","inReplyTo":"pull.1070.git.git.1645029267415.gitgitgadget@gmail.com","subject":"Re: [PATCH] docs: update coding guidelines to be more inclusive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-02-16T22:12:20Z","receivedAt":"2022-02-16T22:12:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Merlin (they/them) via GitGitGadget\" \nwrites:\n\n> These changes make this documentation more inclusive.\n\nI am not sure about this claim, though.\n\n> * Using \"male\" and \"female\" as examples of gender is unnecessary.\n\nIt feels somewhat more excluding for those of us who are non-native\nspeakers to use a heavier-weight word \"gender\". After all, it warns\nagainst writing \"he\", \"him\", \"she\" or \"her\"---the reason why we warn\nagainst the first two is because the author has to implicitly assume\nthe person in question is \"male\". Similarly the latter two needs to\nassume \"female\". These two words, \"male\" and \"female\", are both\neasier to understand to even non-native speakers like us, and at the\nsame time quite in line with the suggestion being offered.\n\nMaybe the motivation behind this change is a misunderstanding that\nsomehow the original of what this patch touches says that \"male\" and\n\"female\" are the only two possible values of \"gender\", but I cannot\nread it that way even when I squint my eyes.\n\n> * The use of \"it\" shouldn't be used to refer to people even in an\n> example of what not to use. People are never \"it\"s.\n\nPeople are never \"it\", but I do not think that is relevant. Reading\nthe original of what this patch touches, the subject is either a\nperson or a program, and for program, referring to \"it\" would be\nperfectly sensible, no?\n\n> * There's no need to specify a person or group of people that learned\n> \"they\" is only plural.\n\nAgain, this change assumes/requires too much knowledge of the\nlanguage, which is more excluding for non-natives who may think\nthere is only one kind of the English language taught everywhere in\nthe world uniformly unless told explicitly. If you are familiar,\nthere may be \"no need\", but does it actively hurt those of you who\nare familiar if the explanation gives such an example? Removing it\nmay actively hurt those who did learn English as a second language.\n\nSo, I can applaud for the desire to be inclusive, but I am not sure\nif the patch succeeds in doing so.\n\nThanks.\n\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1070%2Fmerlinpatt%2Fpatch-1-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1070/merlinpatt/patch-1-v1\n> Pull-Request: https://github.com/git/git/pull/1070\n>\n> Documentation/CodingGuidelines | 16 +++++++---------\n> 1 file changed, 7 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index 711cb9171e0..ffd7fa9c0f4 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -552,9 +552,9 @@ Writing Documentation:\n> Documentation/SubmittingPatches file).\n> \n> In order to ensure the documentation is inclusive, avoid assuming\n> - that an unspecified example person is male or female, and think\n> - twice before using \"he\", \"him\", \"she\", or \"her\". Here are some\n> - tips to avoid use of gendered pronouns:\n> + the gender of an example person, and think twice before using\n> + \"he\", \"him\", \"she\", or \"her\". Here are some tips to avoid the use\n> + of gendered pronouns:\n> \n> - Prefer succinctness and matter-of-factly describing functionality\n> in the abstract. E.g.\n> @@ -566,8 +566,8 @@ Writing Documentation:\n> --short:: Use this to emit output in the short-format.\n> --short:: You can use this to get output in the short-format.\n> --short:: A user who prefers shorter output could....\n> - --short:: Should a person and/or program want shorter output, he\n> - she/they/it can...\n> + --short:: Should a person and/or program want shorter output,\n> + he/she/they can...\n> \n> This practice often eliminates the need to involve human actors in\n> your description, but it is a good practice regardless of the\n> @@ -586,15 +586,13 @@ Writing Documentation:\n> versions.\n> \n> - If you still need to refer to an example person that is\n> - third-person singular, you may resort to \"singular they\" to avoid\n> + third-person singular, you may resort to singular \"they\" to avoid\n> \"he/she/him/her\", e.g.\n> \n> A contributor asks their upstream to pull from them.\n> \n> Note that this sounds ungrammatical and unnatural to those who\n> - learned that \"they\" is only used for third-person plural, e.g.\n> - those who learn English as a second language in some parts of the\n> - world.\n> + learned that \"they\" is only used for third-person plural.\n> \n> Every user-visible change should be reflected in the documentation.\n> The same general rule as for code applies -- imitate the existing\n>\n> base-commit: 225bc32a989d7a22fa6addafd4ce7dcd04675dbf\n"},{"id":"448677","messageId":"220217.86a6epiyii.gmgdl@evledraar.gmail.com","threadId":"57426","inReplyTo":"xmqq4k4ycvgb.fsf@gitster.g","subject":"Re: [PATCH] docs: update coding guidelines to be more inclusive","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-02-17T10:02:11Z","receivedAt":"2022-02-17T10:22:04Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Feb 16 2022, Junio C Hamano wrote:\n\n> \"Merlin (they/them) via GitGitGadget\" \n> writes:\n>\n>> These changes make this documentation more inclusive.\n>\n> I am not sure about this claim, though.\n>\n>> * Using \"male\" and \"female\" as examples of gender is unnecessary.\n>\n> It feels somewhat more excluding for those of us who are non-native\n> speakers to use a heavier-weight word \"gender\". After all, it warns\n> against writing \"he\", \"him\", \"she\" or \"her\"---the reason why we warn\n> against the first two is because the author has to implicitly assume\n> the person in question is \"male\". Similarly the latter two needs to\n> assume \"female\". These two words, \"male\" and \"female\", are both\n> easier to understand to even non-native speakers like us, and at the\n> same time quite in line with the suggestion being offered.\n>\n> Maybe the motivation behind this change is a misunderstanding that\n> somehow the original of what this patch touches says that \"male\" and\n> \"female\" are the only two possible values of \"gender\", but I cannot\n> read it that way even when I squint my eyes.\n\nIsn't that exactly what it's saying? I.e. for the purposes of the\nEnglish used in our documentation there's two grammatical genders \"he\nran the program\", \"she ran the program\" and gender-neutral \"it/they ran\nthe program\".\n\n>> * The use of \"it\" shouldn't be used to refer to people even in an\n>> example of what not to use. People are never \"it\"s.\n>\n> People are never \"it\", but I do not think that is relevant. Reading\n> the original of what this patch touches, the subject is either a\n> person or a program, and for program, referring to \"it\" would be\n> perfectly sensible, no?\n\nYes, as the person who wrote this originally (in\nhttps://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/) that's\nwhat I was going for. It's referring to describing a program as \"it\".\n\n>> * There's no need to specify a person or group of people that learned\n>> \"they\" is only plural.\n>\n> Again, this change assumes/requires too much knowledge of the\n> language, which is more excluding for non-natives who may think\n> there is only one kind of the English language taught everywhere in\n> the world uniformly unless told explicitly. If you are familiar,\n> there may be \"no need\", but does it actively hurt those of you who\n> are familiar if the explanation gives such an example? Removing it\n> may actively hurt those who did learn English as a second language.\n>\n> So, I can applaud for the desire to be inclusive, but I am not sure\n> if the patch succeeds in doing so.\n\nPer what I noted the last time this was discussed I think that we should\nmostly drop this section entirely in favor of some guidelines describing\nhow to actually write the docs that we do write, not what not to do in\nthe rare/nonexistent cases of using grammatical genders:\n\n https://lore.kernel.org/git/87pmwt1dz3.fsf@evledraar.gmail.com/\n\nbrian's follow-up provides a good example of what we try to aim for:\n\n https://lore.kernel.org/git/YMKTARn368Qzsqc2@camp.crustytoothpaste.net/\n\nThe thing that's uninclusive here is asking non-native speakers of\nEnglish who are trying to contribute to this project to grasp some\nfairly advanced linguistic concepts.\n\nI think it's fair to say that the use of \"they\" as a personal pronoun is\nfairly new/novel English language as it's commonly understood. I.e. if\nyou talk to any person who's not a native-level speaker of English it's\na fair assumption that their introductory textbook didn't cover it.\n\nAs noted in those old threads I'm entirely sympathetic to the goal of\navoiding gendered language if it's a thing that matters for some\nreaders, which clearly it does[1].\n\nIt just demonstrably isn't relevant to our documentation in practice, so\nthis whole advice ends up being a bridge to nowhere. It's comparable to\nus carrying C++ coding guide lines in-tree.\n\n1. To be fair, I do find it a bit odd, but then again I'm a non-native\n speaker, and I'm unable to refer to even the monitor, keyboard and\n laptop I'm using to type this in my in my native language without\n assigning the three (different!) genders.\n\n I can assure the concerned native English speakers that by all\n accounts Iceland's got a rather good track record when it comes to\n gender equlity despite that :)\n"},{"id":"448756","messageId":"xmqqfsog512t.fsf@gitster.g","threadId":"57426","inReplyTo":"220217.86a6epiyii.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH] docs: update coding guidelines to be more inclusive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-02-18T03:02:34Z","receivedAt":"2022-02-18T03:02:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n>> Maybe the motivation behind this change is a misunderstanding that\n>> somehow the original of what this patch touches says that \"male\" and\n>> \"female\" are the only two possible values of \"gender\", but I cannot\n>> read it that way even when I squint my eyes.\n>\n> Isn't that exactly what it's saying? I.e. for the purposes of the\n> English used in our documentation there's two grammatical genders \"he\n> ran the program\", \"she ran the program\" and gender-neutral \"it/they ran\n> the program\".\n\nYes, for the purpose of the language, there are only two grammatical\ngenders, \"male\", \"female\" (and \"thing\"). But my point was that the\ndocumentation was not making any non-technical value judgement like\n\"genders outside these two are forbidden\".\n\nWhat I found problematic with the rewrite is that by moving from\nmore concrete examples (\"avoid 'he' and do not assume 'male'\") to a\nmore abstract wording (\"avoid gendered pronouns\"), it would burden\nnon-natives disproportionally more, and I do not see a clear benefit\nto offset the downside.\n\nI do not think it adds anything to discussion to repeat what was\nalready said, so I'll refrain from commenting on the other two\nchanges in the patch, but they posed the same problem to me. I\ncannot convincingly answer with \"yes\" to the question \"does it\noverall help inclusiveness? really? how?\"\n\n\n\n\n\n"},{"id":"448818","messageId":"220219.8635kfhfoy.gmgdl@evledraar.gmail.com","threadId":"57426","inReplyTo":"CAFZ26y3re+fJapXzLOpf73F-ECXhg2sCoBtm_=VUFy5nbN2UVQ@mail.gmail.com","subject":"Re: [PATCH] docs: update coding guidelines to be more inclusive","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-02-18T23:18:35Z","receivedAt":"2022-02-19T00:18:27Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\n[You need to configure your E-Mail client to stop sending HTML E-Mail to\nthe Git mailing list. It's all being rejected by kernel.org. See\ne.g. https://lore.kernel.org/git/pull.1070.git.git.1645029267415.gitgitgadget@gmail.com/\nwhere only your initial posting is visible, but not your replies.\n\nIt's also good etiquette on the ML not to top-post your replies, but to\nreply inline. Except perhaps when not in reply to specific points, such\nas this part of my reply :)\n\nFor other ML readers who weren't directly CC'd I'm quoting your reply to\nmy <220217.86a6epiyii.gmgdl@evledraar.gmail.com> here in full (sent Thu,\n17 Feb 2022 10:51:35 -0500\nas):]\n\nOn Thu, Feb 17 2022, Merlin (they / them) Patterson wrote:\n\n> Removing \"male\" and \"female\" allows for a broader statement of \"don't assume any gender and always keep it gender neutral\".\n> What if I change it to remove the bit about the example person altogether?\n>\n> * In order to ensure the documentation is inclusive, think twice before using\n>\n> 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.\n> I don't think the program part makes sense as part of that example anyway. How about that be separated into its own example?\n>\n> * --short:: Should a person want shorter output, he/she/they can...\n> * --short:: Should a program want shorter output, it can...\n\nYes, as the person who wrote this whole thing initially I don't really\nstand by it, i.e. it was edited from a throwaway comment of mine.\n\nFor what it's worth I don't really find the he/it person/program of it\nambiguous, but what do I know?:)\n\nAside from that referring to an \"it\" in the context of our documentation\n*is* something we need to do. Git the program is often (usually?)\ninvoked by other programs, not directly by human agency.\n\nIn any case, what do you think about this instead:\n\t\n\tdiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n\tindex c37c43186ea..2bcb748aaa3 100644\n\t--- a/Documentation/CodingGuidelines\n\t+++ b/Documentation/CodingGuidelines\n\t@@ -600,12 +600,6 @@ Writing Documentation:\n\t --short:: Use this to emit output in the short-format.\n\t --short:: You can use this to get output in the short-format.\n\t --short:: A user who prefers shorter output could....\n\t- --short:: Should a person and/or program want shorter output, he\n\t- she/they/it can...\n\t-\n\t- This practice often eliminates the need to involve human actors in\n\t- your description, but it is a good practice regardless of the\n\t- avoidance of gendered pronouns.\n\t \n\t - When it becomes awkward to stick to this style, prefer \"you\" when\n\t addressing the the hypothetical user, and possibly \"we\" when\n\t@@ -619,16 +613,10 @@ Writing Documentation:\n\t Use this instead of --xyz. This option might be removed in future\n\t versions.\n\t \n\t- - If you still need to refer to an example person that is\n\t- third-person singular, you may resort to \"singular they\" to avoid\n\t- \"he/she/him/her\", e.g.\n\t-\n\t- A contributor asks their upstream to pull from them.\n\t-\n\t- Note that this sounds ungrammatical and unnatural to those who\n\t- learned that \"they\" is only used for third-person plural, e.g.\n\t- those who learn English as a second language in some parts of the\n\t- world.\n\t+ - Referring to users as a cast of characters (Alice, Bob etc.) or in\n\t+ the third-person singular is too obscure to worry about for the\n\t+ purposes of this style guide. Search the mailing list archive for\n\t+ \"third-person singular\" for more.\n\t \n\t Every user-visible change should be reflected in the documentation.\n\t The same general rule as for code applies -- imitate the existing\n\t\n\n> As for the part about removing \"those who learn English as a second language in some parts of the world.\", I stand by that.\n> Even native English speakers also believe that \"they\" is only a third person plural. That's not restricted to non-native English speakers.\n> 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\n> is irrelevant.\n> How does providing an example benefit anyone?\n\n...\n\nOn Thu, Feb 17 2022, Merlin (they / them) Patterson wrote:\n\n> \"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\n> a person is not thought of as an \"it\".\n>\n> 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.\n>\n> 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\"\n> can only be plural.[...]\n\nI think this came about because of a previous discussion that you'll\nfind in the list archive where some native speakers were maintaining\nthat \"they\" in this context was widely accepted usage because it had\nmade it into some style guides single-digit years ago.\n\nI.e. this was a perhaps flawed attempt to say something like \"this\nphrasing sounds weird, but it's actually correct\".\n\nAs someone who speaks at least 4 languages regularly with levels of\nproficiency ranging from native to something that sound as though I'm\ntrying to butcher the language, I can assure you that advice like that\n*is* really useful to a non-native speaker.\n\nI.e. whatever you or anyone else thinks about this usage of \"they\" it\n*is* relatively obscure usage of English. I'd even bet that for some\nreaders of this document it's the first time they've ever seen it.\n\nSo just like the pronoun \"thy\", it's useful to add a small explanation\nthat it's in fact not a typo or something.\n\n> Explicitly calling out non-native English speakers as making this\n> mistake can have an alienating effect.\n\nI realize I'm just shouting into the ether from my little soap box at\nthis point, but the alienating thing to non-native speakers isn't that\nwe might be told that our English isn't as good as that of non-native\nspeakers.\n\nIt's okey, really. We know.\n\nIt's the opposite, it's that a lot of people aren't assuming that others\nwho who want to participate in this project might have 1/10th of their\nreading comprehension and reading speed when it comes to dense technical\ndocumentation like this.\n\nBecause if they did we might have less of the \"read this before you\ncontribute\" documentation, or more narrowlry tailor it to practical\nissues contributors are likely to encounter.\n\nWhich is why I've been maintaining (and still do) that removing most of\nthis is the right thing to do. It's clearly something anyone maintaining\nour documentation is unlikely to encounter or have to worry about, and\ntherefore doesn't at all belong as a hurdle we put in the way of any new\ncontributor in the form of documentation we advise them to read before\nthey submit their first patch.\n"},{"id":"448929","messageId":"YhKxVBReUMJUB0tw@camp.crustytoothpaste.net","threadId":"57426","inReplyTo":"220219.8635kfhfoy.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH] docs: update coding guidelines to be more inclusive","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2022-02-20T21:23:32Z","receivedAt":"2022-02-20T21:23:40Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2022-02-18 at 23:18:35, Ævar Arnfjörð Bjarmason wrote:\n> I think this came about because of a previous discussion that you'll\n> find in the list archive where some native speakers were maintaining\n> that \"they\" in this context was widely accepted usage because it had\n> made it into some style guides single-digit years ago.\n\nSingular they has been in common use for centuries. It became less\ncommon for many years because prescriptivists proposed using \"he\" to\nrefer to people of all genders, which was in common use for a long time,\nuntil it was widely criticized as being sexist (and also, at times,\nsounding bizarre). \"He or she\" was then used in formal writing, but\nthat was also criticized as not being inclusive as well as being wordy\nand awkward. During this entire time, singular they has remained in\ncommon use in speech and informal writing and is widely recognized as\npart of the English language.\n\nIt's true that it is only now becoming more acceptable in formal\nwriting, but it is well known and commonly used in English as a whole\nand has been for a long time.\n\nI will also freely admit that for people who have learned English as a\nsecond language sometime in the past, this would probably not have been\ncovered in the textbook. As I continue to use Spanish, I learn things\nabout the language and how it's used today that differ from what I\nlearned when I started learning it formally over two decades ago, and\nthat's okay. Language evolves and as speakers of a second or third\nlanguage, we'll have to evolve with it.\n\n> I.e. this was a perhaps flawed attempt to say something like \"this\n> phrasing sounds weird, but it's actually correct\".\n> \n> As someone who speaks at least 4 languages regularly with levels of\n> proficiency ranging from native to something that sound as though I'm\n> trying to butcher the language, I can assure you that advice like that\n> *is* really useful to a non-native speaker.\n\nI agree, this context would be helpful. Maybe, if we retain this, we\ncan just explicitly say, \"Even though some non-native speakers may find\nthe use of singular they unusual, it is in fact common in English and\npreferred in our documentation.\"\n\n> I.e. whatever you or anyone else thinks about this usage of \"they\" it\n> *is* relatively obscure usage of English. I'd even bet that for some\n> readers of this document it's the first time they've ever seen it.\n\nIt is simply not the case that this is obscure. As I've said in the\npast, singular they, in the sense of referring to a single person whose\ngender is unknown or irrelevant, has been in use since the 14th century\nand has been used by William Shakespeare, Lord Byron, and Jane Austen.\nIt is routinely used for this purpose by fluent non-native speakers as\nwell (I have noted colleagues doing this).\n\nI will admit that using they as the pronoun for a person whose gender is\nknown and who has explicitly requested the use of this pronoun is much\nmore recent, which probably dates to the mid 20th century (albeit at a\nmuch lower frequency than today), but this is not the context in which\nwe are using the pronoun in our documentation.\n\nIt may be that for some readers it is the first time they've seen it,\nbut it will be far from the last if they continue to read English.\nUnderstanding the main idea of a technical document in one's specialized\nfield (e.g., the Git documentation) is part of the CEFR B2 level, and at\nthat point, I'd expect the reader to have read numerous news articles\nand online documents where this usage is common or becoming so.\n\nAs to your suggestion to this effect, I should point out that I'm fine\nwith removing this text from the documentation, as you suggested,\nprovided we can stop having extended debates about it on the list.\n-- \nbrian m. carlson (he/him or they/them)\nToronto, Ontario, CA\n"}]}