| Message ID | f06092a9053e40d93c4ec94b7fbbb1b8d563957b.1623766273.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Avoid gendered pronouns | expand |
On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote: > [...] > * References to fictional people with clear genders (e.g. Alice and > Bob). I mentioned in the feedback on an earlier round[1] that aside from your goals, these would be better rewritten. I've just submitted a series[2] to do that; perhaps you can look at that and see if you think there's still a reason to explicitly exclude these. > * Sample text used in test cases (e.g t3702, t6432). FWIW that's another unaddressed-by-you question I had in an earlier round[1]. > [...] > 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. In the same E-Mail that you copied the original version of this new text from[3], Junio suggested, mostly in reference to my [4]: I tend to agree that Ævar's approach to guidelines is to cover more general readability tips, not necessarily focusing on avoidance of gendered pronouns, let alone encouraging of "singular they". I think that is overall a good approach to advance the "let's make sure the document is easier to read by everybody" goal than mechanical "he and she are bad, let's use they" does. To be fair he does go on to say something that suggests to also go for a version of your approach here, i.e. that we still have some reference to "they" over "he" and "she". I've got no problem with that, but he also said (comments in [] are mine): If we were to go that route [(of copying Junio's version from [3])], I think the first two points [(i.e. the first two bullet-points you incorporated above)] (which I didn't give enough thought to be even called a "draft") should be replaced with something like what Ævar wrote in his write-up. So your version here does none of that, and we're mostly left with advice about what not to do in the demonstrably obscure edge case of gendered language in our docs (as evidenced by the diffstat). But we aren't helping contributors much with with positive examples of what to do unrelated to that, i.e. for documentation they could actually be expected to write or maintain. I.e. general prose guidelines for common the cases of discussing command-line options, program behavior, user interaction etc. Anyway, I don't think I'll be participating in this topic any further. It seems you're not interested in pursuing alternate approaches that accomplish your goals, or in responding to specific point-by-point feedback on your series from myself and others. I do think it would be a much better and respectful use of everyone's time on this ML if you clearly stated your unwillingness to deviate from the narrow approach in the initial version of a series you're submitting. Maybe I'm wrong and you are willing to incorporate something like more general prose that accomplishes most or all of your narrow goals as a side-effect, but right now it seems you're not. If we're going to make some use of the collective time spent by a lot of people on-list reading the documentation you're suggesting to change, that'll have to be done in a series that would textually conflict with yours (and which Junio would need to clean up), or in something that would build on top of your more narrowly focused work. 1. https://lore.kernel.org/git/875yyp4fun.fsf@evledraar.gmail.com/ 2. https://lore.kernel.org/git/cover-0.6-00000000000-20210615T161330Z-avarab@gmail.com/ 3. https://lore.kernel.org/git/xmqqr1h51dce.fsf@gitster.g/ 4. https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/
Derrick Stolee via GitGitGadget wrote: > 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. The gender of the reader is never specified. The documentation doesn't mention users in that way, only third-person developers, reviewers, etc. The code mentions third-person users. Never the reader. So it's not true the reader can experience cognitive dissonance when the gender ofthe reader is specified, because we never do that. Do you have an actual example?
Ævar Arnfjörð Bjarmason wrote: > On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote: > Anyway, I don't think I'll be participating in this topic any > further. It seems you're not interested in pursuing alternate approaches > that accomplish your goals, or in responding to specific point-by-point > feedback on your series from myself and others. > > I do think it would be a much better and respectful use of everyone's > time on this ML if you clearly stated your unwillingness to deviate from > the narrow approach in the initial version of a series you're > submitting. For what it's worth I also feel that's the case. 95% of my suggestions for improvement were completely ignored, and it's only when the maintainer threatened to merge my competing series, that I started receiving responses. I don't believe critical feedback has been welcomed, I don't believe my time as a reviewer was respected, and mostly it felt like talking to a wall. I find it ironic that a patch series that boasts of promoting inclusion and diversity completely ignores the most important diversity the project should care about: Diversity of thought. While claiming to be trying to avoid hypothetical people from feeling excluded, it actively excluded the opinions of actual people.
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote: > ... >> + 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. "singular". By the way, I do not mind toning down "if you absolutely need to ... resort to" that discourages "singular they". I just wanted writers to consider that the language evolves slowly, and if they think "singular they" is the best vehicle to phrase what they want to say even after considering that it may sound distracting to foreigners, I would not stop them. > To be fair he does go on to say something that suggests to also go for a > version of your approach here, i.e. that we still have some reference to > "they" over "he" and "she". I've got no problem with that, but he also > said (comments in [] are mine): > > If we were to go that route [(of copying Junio's version from [3])], > I think the first two points [(i.e. the first two bullet-points you > incorporated above)] (which I didn't give enough thought to be even > called a "draft") should be replaced with something like what Ævar > wrote in his write-up. FWIW, I am not happy with this version for that reason, either. I wonder if replacing the first two bullet points ("Removing" and "If you need to talk about") above with what was added to the CodingGuidelines by the "succinct matter-of-factly description" in https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/ would be sufficient. Thanks.
Junio C Hamano <gitster@pobox.com> writes: > FWIW, I am not happy with this version for that reason, either. > > I wonder if replacing the first two bullet points ("Removing" and > "If you need to talk about") above with what was added to the > CodingGuidelines by the "succinct matter-of-factly description" in > > https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/ > > would be sufficient. So, here is what I plan to queue on top of these four patches to replace my "not even draft" garbage with what you wrote, with a bit of copyediting. Comments? diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 605f924981..476b840d30 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -546,28 +546,43 @@ Writing Documentation: 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. + - 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
On 16/06/21 12.06, 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. > I'm also confused and found that using singular they may sound odd. So IMO either avoid referring to third-person singular (gendered pronouns) or write using plural actors. In the case above it should be `Contributors ask their upstream to pull from them, potentially with reviews`. A prime example of rewriting using plural actors is in "doc: avoid using the gender of other people" patch [1], which said the diff: > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 55287d72e0..3e215f4d80 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -373,9 +373,8 @@ If you like, you can put extra tags at the end: > . `Acked-by:` says that the person who is more familiar with the area > the patch attempts to modify liked the patch. > . `Reviewed-by:`, unlike the other tags, can only be offered by the > - reviewer and means that she is completely satisfied that the patch > - is ready for application. It is usually offered only after a > - detailed review. > + reviewers themselves when they are completely satisfied with the > + patch after a detailed analysis. > . `Tested-by:` is used to indicate that the person applied the patch > and found it to have the desired effect. I'm OK with using they in plural context, but not as singular they. [1]: https://lore.kernel.org/git/20210611202819.47077-2-felipe.contreras@gmail.com/
On 6/16/2021 1:06 AM, Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: > >> FWIW, I am not happy with this version for that reason, either. >> >> I wonder if replacing the first two bullet points ("Removing" and >> "If you need to talk about") above with what was added to the >> CodingGuidelines by the "succinct matter-of-factly description" in >> >> https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/ >> >> would be sufficient. > > So, here is what I plan to queue on top of these four patches to > replace my "not even draft" garbage with what you wrote, with a bit > of copyediting. > > Comments? ... > + - 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. I wasn't a huge fan of this "example first" approach, but you did a good job of tying it to the purpose and the rest of the recommendations. > + - 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. This version looks good to me. It is probably worth adding Ævar in a Co-authored-by line. Thanks, -Stolee
On Wed, Jun 16 2021, Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: > >> FWIW, I am not happy with this version for that reason, either. >> >> I wonder if replacing the first two bullet points ("Removing" and >> "If you need to talk about") above with what was added to the >> CodingGuidelines by the "succinct matter-of-factly description" in >> >> https://lore.kernel.org/git/87a6nz2fda.fsf@evledraar.gmail.com/ >> >> would be sufficient. > > So, here is what I plan to queue on top of these four patches to > replace my "not even draft" garbage with what you wrote, with a bit > of copyediting. > > Comments? > > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 605f924981..476b840d30 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -546,28 +546,43 @@ Writing Documentation: > 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. > + - 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 That mostly-my-draft was hastily a written one-off, perhaps this is better and a more exhaustive discussion of common cases: - Discussing command-line options, and program functionality: Prefer succinctness and matter-of-factly describing functionality in the abstract. E.g. --short:: Emit output in the short-format. Avoid more verbose constructions, such as: --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... - Addressing the reader: Address the reader of the documentation directly with "you", e.g. "you can do xyz". - Discussing Git, "the command" etc.: Use "we" when discussing how the program might react to the user, or perhaps "git" or "the command", e.g.: we might store the data[...] git will emit[...] the command will[...] - Discussing other users: When referring to other users on the same system prefer talking about "a user" or "another user". There's usually no reason to invent a cast of characters with names, titles and hobbies. Your OS's users don't cleanly map onto any particular people, a user of git might be having a merge conflict with another person, or an automated commit from a cron daemon. We prefer the style typical of standard library adn system tooling documentation in this and most other cases, you can look at the documentation of chmod(2) and other commands, syscalls and libraries that deal with UIDs or GIDs for examples. - Discussing other systems: As with discussing other users, git might interact with other systems over the network. In these cases we also avoid a cast of characters, preferring to talk about concepts like "fetching data from a remote", having a conflict with "diverging histories" etc. The references to "gendered prounouns" etc. are gone, perhaps there's a good reason to re-include them, but the point of "isn't that issue solved by recommending an orthagonal approach?" is one of the many things Stolee hasn't been addressing in the threads related to this series. To me that whole approach is somewhere between a solution in search of a problem and a "let's fix it and move on". Not something we need explicitly carry in our CodingGuidelines forever. The v1 of this series started with decreeing that nobody should be using gendered language in commit messages. It seems that the discussion I started that perhaps that was overly pedantic and unfriendly to people struggling with English won out, so that's gone in recent revisions. That's left only a handful of examples \b(?:she|he)\b in our docs, we have outstanding patches to fix those, and draft guidelines (amended above) to thoroughly lead documentation writers in other directions. It just seems superfluous to me to insist on enumerating increasingly obscure and disfavored alternatives to what we suggest as preferred prose in our documentation. For example, we have around the same order of magnitude of "one might" in Documentation/, I think we should probably just fix that and move on, not forever have a guideline against overly formal or "Shakespearean language" in the guidelines.
Ævar Arnfjörð Bjarmason wrote: > It just seems superfluous to me to insist on enumerating increasingly > obscure and disfavored alternatives to what we suggest as preferred > prose in our documentation. For example, we have around the same order > of magnitude of "one might" in Documentation/, I think we should > probably just fix that and move on, not forever have a guideline against > overly formal or "Shakespearean language" in the guidelines. I also don't see much point in writing guidelines for something that doesn't come up often, and hasn't come up in more than 15 years of life of the project. Does not smell like an issue.
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > - Discussing command-line options, and program functionality: > > Prefer succinctness and matter-of-factly describing functionality in > the abstract. E.g. > > --short:: Emit output in the short-format. > > Avoid more verbose constructions, such as: > > --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 applies the most broadly and addresses common readability issues, which is why I like this part the most. > - Addressing the reader: > - Discussing Git, "the command" etc.: I am not sure if these are even worth saying, especially when we do not explain why we recommend to do so. > - Discussing other users: > > When referring to other users on the same system prefer talking > about "a user" or "another user". There's usually no reason to > invent a cast of characters with names, titles and hobbies. > > Your OS's users don't cleanly map onto any particular people, a user > of git might be having a merge conflict with another person, or an > automated commit from a cron daemon. > > We prefer the style typical of standard library adn system tooling > documentation in this and most other cases, you can look at the > documentation of chmod(2) and other commands, syscalls and libraries > that deal with UIDs or GIDs for examples. I cannot exactly put my fingers on where this feeling comes from, but this part appears to spend many lines to tell me very little. For example, it is unclear why the second paragraph is there at all. Sure, some commits may be created by a non people, but how does that fact affect how I write the documentation? Writing about such an activity by non people, what are our recommendations? The third paragraph does not do much better. Unless you have UNIX man pages handy, chmod(2) may not be very easily accessible. It feels as if it wants to encourage descriptions without human actors, without doing a very good job at explaining to readers why the guideline does not want to see them in our documentation. Unlike chmod(2) and getpwnam(3), but more like any dSCM, Git is a tool to help inter-person communication, and at some point we will have to talk about contributors asking their upstreams to pull their work from their repositories. It won't be like system calls dealing with pure numbers. We do not have to give them names like Alice and Bob, but we do have to refer to repositories of these cast of characters individually to clearly explain/describe how data flow among them. > - Discussing other systems: > > As with discussing other users, git might interact with other > systems over the network. In these cases we also avoid a cast of > characters, preferring to talk about concepts like "fetching data > from a remote", having a conflict with "diverging histories" etc. Unlike the above "other users", I have littleproblem with this part. It however feels funny to warn against use of "cast of characters", when the first sentence talks about "with other systems", which are clearly not people. Even when you are "fetching from a remote", you are getting the result of work by "other people", so I would not have separated "other users" and "other systems" in separate sections. > The references to "gendered prounouns" etc. are gone, perhaps there's a > good reason to re-include them, but the point of "isn't that issue > solved by recommending an orthagonal approach?" is one of the many > things Stolee hasn't been addressing in the threads related to this > series. > > To me that whole approach is somewhere between a solution in search of a > problem and a "let's fix it and move on". Not something we need > explicitly carry in our CodingGuidelines forever. This I think is the crux of the differences between you two. I'd love to hear Derrick's response and eventually see a middle ground reached.
On 6/16/2021 8:09 PM, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: ... >> The references to "gendered prounouns" etc. are gone, perhaps there's a >> good reason to re-include them, but the point of "isn't that issue >> solved by recommending an orthagonal approach?" is one of the many >> things Stolee hasn't been addressing in the threads related to this >> series. >> >> To me that whole approach is somewhere between a solution in search of a >> problem and a "let's fix it and move on". Not something we need >> explicitly carry in our CodingGuidelines forever. > > This I think is the crux of the differences between you two. I'd > love to hear Derrick's response and eventually see a middle ground > reached. I disagree that removing gendered pronouns and updating the guidelines are orthogonal. At minimum, we shouldn't have guidelines that we do not follow, especially when they are small in number and we can fix them in a few patches. The entire point of this series was to reach a decision about gendered pronouns so we can stop having arguments about them when they come up. We should just be able to point to "here is the decision we made" and it's not enough to say "If you go look at the mailing list archive you can see that we removed all gendered pronouns so you shouldn't add them again." We need ways for contributors to self-discover these things. Anything less is doing a disservice to our fellow contributors. Thanks, -Stolee
Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > > > On Tue, Jun 15 2021, Derrick Stolee via GitGitGadget wrote: > By the way, I do not mind toning down "if you absolutely need to > ... resort to" that discourages "singular they". I just wanted > writers to consider that the language evolves slowly, and if they > think "singular they" is the best vehicle to phrase what they want > to say even after considering that it may sound distracting to > foreigners, Once again, it's not just foreigners. Even native speakers who are professional lingusits see a problem with some usages of singular "they". Like mushrooms: not all uses of singular "they" are good.
On Thu, Jun 17 2021, Derrick Stolee wrote: > On 6/16/2021 8:09 PM, Junio C Hamano wrote: >> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > ... >>> The references to "gendered prounouns" etc. are gone, perhaps there's a >>> good reason to re-include them, but the point of "isn't that issue >>> solved by recommending an orthagonal approach?" is one of the many >>> things Stolee hasn't been addressing in the threads related to this >>> series. >>> >>> To me that whole approach is somewhere between a solution in search of a >>> problem and a "let's fix it and move on". Not something we need >>> explicitly carry in our CodingGuidelines forever. >> >> This I think is the crux of the differences between you two. I'd >> love to hear Derrick's response and eventually see a middle ground >> reached. > > I disagree that removing gendered pronouns and updating the > guidelines are orthogonal. At minimum, we shouldn't have > guidelines that we do not follow, especially when they are > small in number and we can fix them in a few patches. Sorry, I read that a few times and I'm still not sure I get it. Do you mean by "we shouldn't have guidelines that we do not follow" that we shouldn't engage in general tree-wide fixes unless we also have documented guidelines to back them up? Or that the tree-wide changes for existing occurrences cannot be separated from having specific documented advice applicable to those occurances, or...? If it's the first we have a bunch of tree-wide fixes that don't result in documented guidelines, e.g. we did a general replacement of http with https links recently. See 6eda9ac9e5 (doc: use https links, 2021-02-05). That's generally considered a good idea, I don't think we have a guideline, and I'd think we *probably* wouldn't need one for reasons similar to what I'm maintaining here. > The entire point of this series was to reach a decision about > gendered pronouns so we can stop having arguments about them > when they come up. Where have we been having those arguments? A reverse search of the ML for all time reverse ordered by date for the term shows the 20th result as the greater topic of this thread: https://lore.kernel.org/git/?q=pronouns&o=-1 You need to search a bit further to get to this thread, or the ~120th result for "gendered". Much of the earlier is false positives, and skimming it to the extent that it's code I'd say those cases would fall squarely under more "be brief, be succinct, UIDs aren't people" etc. advice: https://lore.kernel.org/git/?q=gendered&o=-1 In that context your "so we can stop[...]" somewhat sounds like "take my patches, or I won't stop talking about my patches" :) > We should just be able to point to "here is > the decision we made" and it's not enough to say "If you go > look at the mailing list archive you can see that we removed > all gendered pronouns so you shouldn't add them again." And I'd probably agree with you if you were providing examples of how this is really some ongoing confusion, or pointing out how specific parts of the documentation, code, comments etc. that we're now aren't going to have that problem solved as a byproduct of more generally applicable style guide advice. Can you point out specific hunks that you, me or Felipe have changed in our respective patches on this greater topic that wouldn't implicitly be covered under something like the advice I'm proposing upthread[1]? > We need ways for contributors to self-discover these things. > Anything less is doing a disservice to our fellow contributors. We're in full agreement with that. I've often started writing some documentation patch and genuinely forgotten what the general tone of our documentation is. Should I write "an option such as this", "this option", say "you can do", or "a user might" etc? I've then gone paging through the Documentation/ directory, and not being sure what's considered good current practice, and what's historical. So I think we absolutely need general advice on how we write our documentation, their tone, how we talk about common things like CLI switches, program interaction etc. But here in 1/4 we have two doc hunks being changed, one from 2007, one from 2013. In 2/4 we've got 6 occurances in the whole tree. 2 are from Junio and the last time he sinned in that particular area was 2013. 2 are from a 2019 GSOC intern adding "she", one more from Jeff King in 2015, and one in 2014 from a person who last got a patch in git.git in in that same year. I'm avoiding naming that 2019 GSOC intern b.t.w. because I for one wouldn't want to contribute to a project like git, do a search for my name on lore.kernel.org/git/ and see this thread. I.e. see that my addition of a pronoun referring to my gender in a comment has somehow become something that must be eliminated ... in order to get people like myself to feel like their contributions are more welcome. That's less welcoming, not more. Just like this whole thread-at-large started by pouncing on another non-native English speaker's recent and obviously innocent use of the wrong pronoun in a commit message. But I digress. Going on, 3/4 are simple typos, and your original 4/4 is an implicit suggestion that (by approximate line count) 5% of everyone's time spent reading through CodingGuidelines is best spent reading about this always-obscure-and-now-gone-from-the-tree "issue" addressed in the previous 3 patches. I'm suggesting that 5% of their time would be better spent on something that clearly has direct applicability to the maintenance of existing code and documentation, and the authoring of new works. I also think it happens to gives you 100% of the end result you want in terms of what code/docs we end up with in-tree. 1. https://lore.kernel.org/git/87bl85y15s.fsf@evledraar.gmail.com
Junio C Hamano wrote: > - - 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"). Here is another escape hatch recommended by linguists before attempting to use singular "they": - Use a generic alternative and count on the reader's common sense. Instead of saying "she made a mistake", say "a mistake was made". > - 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. For the nth time, it's not just foreign speakers: https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they > + - 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. These look OK to me, but I wonder why we have writing tips in *coding* guidelines. We are not writing a style manual, there's plenty of other tips writers of documentation, commit messages and comments could use, why are we only giving tips for gender pronouns? Why don't we have a section on passive vs. active voice? How about avoiding zombie nouns? Adjectives and adverbs? That vs. which? Who and whom? I don't think there's much value in trying to codify what is a good sense of style while writing just for one particular non-issue. Cheers.
Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > > The references to "gendered prounouns" etc. are gone, perhaps there's a > > good reason to re-include them, but the point of "isn't that issue > > solved by recommending an orthagonal approach?" is one of the many > > things Stolee hasn't been addressing in the threads related to this > > series. > > > > To me that whole approach is somewhere between a solution in search of a > > problem and a "let's fix it and move on". Not something we need > > explicitly carry in our CodingGuidelines forever. > > This I think is the crux of the differences between you two. I'd > love to hear Derrick's response and eventually see a middle ground > reached. A middle ground is not always the best solution. The solution between punching people you disagree with and tolerance is not punching them a little bit. Sometimes one side is just incorrect. Also, a principle of logic is the burden of proof. Ævar doesn't have to prove that there's something wrong with Derek's proposal, Derek has the burden of proof. Why do we need a writing style lesson for one particular issue (that has never really been an issue) in CodingGuidelines? I have not seen an answer to that question--let alone a satisfactory one.
Derrick Stolee wrote: > On 6/16/2021 8:09 PM, Junio C Hamano wrote: > > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > ... > >> The references to "gendered prounouns" etc. are gone, perhaps there's a > >> good reason to re-include them, but the point of "isn't that issue > >> solved by recommending an orthagonal approach?" is one of the many > >> things Stolee hasn't been addressing in the threads related to this > >> series. > >> > >> To me that whole approach is somewhere between a solution in search of a > >> problem and a "let's fix it and move on". Not something we need > >> explicitly carry in our CodingGuidelines forever. > > > > This I think is the crux of the differences between you two. I'd > > love to hear Derrick's response and eventually see a middle ground > > reached. > > I disagree that removing gendered pronouns and updating the > guidelines are orthogonal. We already know that. We are waiting for an *explanation*. Why?
On Thu, Jun 17 2021, Junio C Hamano wrote: > Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: > >> - Discussing command-line options, and program functionality: >> >> Prefer succinctness and matter-of-factly describing functionality in >> the abstract. E.g. >> >> --short:: Emit output in the short-format. >> >> Avoid more verbose constructions, such as: >> >> --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 applies the most broadly and addresses common readability > issues, which is why I like this part the most. *nod* >> - Addressing the reader: >> - Discussing Git, "the command" etc.: > > I am not sure if these are even worth saying, especially when we do > not explain why we recommend to do so. Maybe not, I tried to just grep around / search in my memory for how we talk about this, to cover that base. I.e. when we talk about "you", then other commands (this part), permissions, remote users etc... >> - Discussing other users: >> >> When referring to other users on the same system prefer talking >> about "a user" or "another user". There's usually no reason to >> invent a cast of characters with names, titles and hobbies. >> >> Your OS's users don't cleanly map onto any particular people, a user >> of git might be having a merge conflict with another person, or an >> automated commit from a cron daemon. >> >> We prefer the style typical of standard library adn system tooling >> documentation in this and most other cases, you can look at the >> documentation of chmod(2) and other commands, syscalls and libraries >> that deal with UIDs or GIDs for examples. > > I cannot exactly put my fingers on where this feeling comes from, > but this part appears to spend many lines to tell me very little. > > For example, it is unclear why the second paragraph is there at all. > Sure, some commits may be created by a non people, but how does that > fact affect how I write the documentation? Writing about such an > activity by non people, what are our recommendations? The third > paragraph does not do much better. Unless you have UNIX man pages > handy, chmod(2) may not be very easily accessible. It feels as if > it wants to encourage descriptions without human actors, without > doing a very good job at explaining to readers why the guideline > does not want to see them in our documentation. The real problem here is that a clearly overly verbose person is trying to write guidelines about how to be less verbose :) Yes, that can probably go entirely. > Unlike chmod(2) and getpwnam(3), but more like any dSCM, Git is a > tool to help inter-person communication, and at some point we will > have to talk about contributors asking their upstreams to pull their > work from their repositories. It won't be like system calls dealing > with pure numbers. We do not have to give them names like Alice and > Bob, but we do have to refer to repositories of these cast of > characters individually to clearly explain/describe how data flow > among them. I'd think that the *nix permission model in general and FS-like permission models (including pseudo-implementations thereof, such as Google Docs sharing etc.) in general are a much bigger helper of inter-persion communication than Git is. Which is what I was trying to aim for, the documentation for such systems can usually talk about the permission models and "foreign" data in matter of fact terms. E.g. we really don't need to drag up an example of another person on the system to explain core.sharedRepository to you, or more generally why you get a permission error when you "cat" something on a *nix system. But yes, could be improved etc.; does anyone have a better suggestion? I think whatever I come up with at this point is probably much better copyedited by others. >> - Discussing other systems: >> >> As with discussing other users, git might interact with other >> systems over the network. In these cases we also avoid a cast of >> characters, preferring to talk about concepts like "fetching data >> from a remote", having a conflict with "diverging histories" etc. > > Unlike the above "other users", I have littleproblem with this part. > It however feels funny to warn against use of "cast of characters", > when the first sentence talks about "with other systems", which are > clearly not people. Even when you are "fetching from a remote", you > are getting the result of work by "other people", so I would not > have separated "other users" and "other systems" in separate > sections. What I was trying to go for here is that we could say you do a fetch, get a divergent branch, and a conflict, and then proceed from there. It's just a distraction in such examples to set up a scenario where J. Doe is the author of those commits, you can't reach them at the office right now (maybe they're at lunch), but you need to resolve the conflict yourself etc... >> The references to "gendered prounouns" etc. are gone, perhaps there's a >> good reason to re-include them, but the point of "isn't that issue >> solved by recommending an orthagonal approach?" is one of the many >> things Stolee hasn't been addressing in the threads related to this >> series. >> >> To me that whole approach is somewhere between a solution in search of a >> problem and a "let's fix it and move on". Not something we need >> explicitly carry in our CodingGuidelines forever. > > This I think is the crux of the differences between you two. I'd > love to hear Derrick's response and eventually see a middle ground > reached. Covered downthread.
Ævar Arnfjörð Bjarmason wrote: > > I'm suggesting that 5% of their time would be better spent on something > that clearly has direct applicability to the maintenance of existing > code and documentation, and the authoring of new works. I also think it > happens to gives you 100% of the end result you want in terms of what > code/docs we end up with in-tree. Agreed, but what about *our* time? I feel like we already have spent more than ten times the amount of time this non-issue warranted. Can we return to do something actually productive? I vote for a moratorium on this issue. Can we leave this as it is and return back to it in a month or so?
On 2021-06-17 at 13:22:21, Derrick Stolee wrote: > On 6/16/2021 8:09 PM, Junio C Hamano wrote: > I disagree that removing gendered pronouns and updating the > guidelines are orthogonal. At minimum, we shouldn't have > guidelines that we do not follow, especially when they are > small in number and we can fix them in a few patches. > > The entire point of this series was to reach a decision about > gendered pronouns so we can stop having arguments about them > when they come up. We should just be able to point to "here is > the decision we made" and it's not enough to say "If you go > look at the mailing list archive you can see that we removed > all gendered pronouns so you shouldn't add them again." I agree. Part of the complaint in the previous thread was that we were overly debating people's commit messages, which can be demoralizing to contributors, especially new ones. It's much better to decide on an approach, document it, and then, if there's an issue, we can just point people to the documentation. And, judging by the amount of discussion around this topic, it would be helpful to avoid rehashing the same discussion again and again. I certainly would prefer to not have this discussion multiple times.
On 2021-06-16 at 19:54:20, Ævar Arnfjörð Bjarmason wrote: > The references to "gendered prounouns" etc. are gone, perhaps there's a > good reason to re-include them, but the point of "isn't that issue > solved by recommending an orthagonal approach?" is one of the many > things Stolee hasn't been addressing in the threads related to this > series. I think I've addressed this. Sometimes you can avoid referring to people and therefore avoiding pronouns, and sometimes the prose reads better if you talk about the user or actor. Also, sometimes you need to discuss a matter at length and using variety in your language is desirable, so you may want to, for example, avoid continually using the passive voice to discuss the topic. I don't think it's fair to just say "don't refer to the user or other humans if you'd need to use third-person pronouns" because I don't think that's applicable in all cases. I, for one, don't intend to write my commit messages in that way because I think it will make them substantially worse. For example, I often discuss the behavior or expectations of users when writing FAQ entries or other documentation and sometimes we'll need to use pronouns. I agree that in many cases we can effectively rephrase to avoid needing to do this, but if we acknowledge that sometimes we will need to write using third-person personal pronouns in some cases, it's worth documenting what those should be.
On Fri, Jun 18 2021, brian m. carlson wrote: > [[PGP Signed Part:Undecided]] > On 2021-06-16 at 19:54:20, Ævar Arnfjörð Bjarmason wrote: >> The references to "gendered prounouns" etc. are gone, perhaps there's a >> good reason to re-include them, but the point of "isn't that issue >> solved by recommending an orthagonal approach?" is one of the many >> things Stolee hasn't been addressing in the threads related to this >> series. > > I think I've addressed this. Sometimes you can avoid referring to > people and therefore avoiding pronouns, and sometimes the prose reads > better if you talk about the user or actor. Also, sometimes you need to > discuss a matter at length and using variety in your language is > desirable, so you may want to, for example, avoid continually using the > passive voice to discuss the topic. > > I don't think it's fair to just say "don't refer to the user or other > humans if you'd need to use third-person pronouns" because I don't think > that's applicable in all cases. I, for one, don't intend to write my > commit messages in that way because I think it will make them > substantially worse. You won't have to. Reading this and your slightly earlier <YMvoNcFXnHo0KXH3@camp.crustytoothpaste.net> I think you've missed that as of v2[1] of this series the proposal to is not to enforce this policy on people's commit messages; so we're only talking about code comments and documentation at this point. > [...]For example, I often discuss the behavior or > expectations of users when writing FAQ entries or other documentation > and sometimes we'll need to use pronouns. > > I agree that in many cases we can effectively rephrase to avoid needing > to do this, but if we acknowledge that sometimes we will need to write > using third-person personal pronouns in some cases, it's worth > documenting what those should be. I agree with you as a general matter that anything we come up with, whether it's a prose guideline, coding style etc. won't cover all cases. But perhaps we disagree on whether that should be a goal of our guidelines at all. I don't think it should. It shouldn't because it simply won't work, the amount of guidelines we ask contributors to read becomes a zero-sum game at some point. Assuming that most contributors attempt to at least skim them we've already reached that point. It's a trivial task to find recent submissions of patches that violate one guideline or another. So the criteria for inclusion shouldn't be whether we can think of cases they apply to, but whether those cases are common enough to warrant explicit mention, keeping in mind that any new addition will dilute whatever advice we're already giving. Having gone over the number of occurances we're fixing [2] I don't see how this qualifies. As Stolee said upthread[3], referring to Documentation/CodingGuidelines ("[]" edits of what I understood him to mean are mine): [It's the document that we] should just be able to point to [say] "here is the decision we made" I just don't think that should be a primary or secondary goal of that document. We have e.g. this mailing list discussion to point to for some decision we made. The CodingGuidelines is what we're asking people to read when they've e.g. found some data-eating bug in git and are about to send us a patch, but before that we're asking them to go through a fuzzy checklist of items checklist. It's already 20 pages in my browser if I were to try to print it. 1. https://lore.kernel.org/git/pull.975.v2.git.1623246878.gitgitgadget@gmail.com/ 2. https://lore.kernel.org/git/87o8c4wkn7.fsf@evledraar.gmail.com/ 3. https://lore.kernel.org/git/5755690e-ef13-e12c-4b10-9cb303ae843a@gmail.com/
brian m. carlson wrote: > And, judging by the amount of discussion around this topic, it would be > helpful to avoid rehashing the same discussion again and again. I > certainly would prefer to not have this discussion multiple times. I'm sure plenty of people would prefer not to have a discussion about abortion multiple times either, but that's the nature of living in a society. There will always be differing opinions, and as long you are trying to impose your opinion on others, there will be discussion.
Ævar Arnfjörð Bjarmason wrote: > The CodingGuidelines is what we're asking people to read when they've > e.g. found some data-eating bug in git and are about to send us a patch, > but before that we're asking them to go through a fuzzy checklist of > items checklist. It's already 20 pages in my browser if I were to try to > print it. Exactly. Moreover, the point a guideline is on the name: guide. After reading it developers should feel they are heading in the right direction, but they won't know everything there is to know about git.git development, that requires many years of practice, and mistakes. More importantly than what it is, is what it's not: by-laws. A developer that misses a point in the guidelines should not be reprimended and sent to the brig. Instead she should merely be directed to it. Another thing it shouldn't be is a tool to win arguments. If two developers argue about sentence spacing (one space vs. two spaces), even if the whole community agrees two spaces is preferable--and thus one developer "won" the argument--that still doesn't merit writing it down to further rub it in. Not everything belongs in the guideline; only the most salient tips that guide newcomers in the right direction. Cheers.
"brian m. carlson" <sandals@crustytoothpaste.net> writes: > I agree that in many cases we can effectively rephrase to avoid needing > to do this, but if we acknowledge that sometimes we will need to write > using third-person personal pronouns in some cases, it's worth > documenting what those should be. I think we've heard enough from both sides and there probably is not misunderstanding among the folks, even though there are differences of opinions. I would like to consider that the last draft I did [*1*] based on earlier suggestions by Derrick and Ævar would be a reasonable middle ground. I'll go mostly offline next week---I'd notice if the list came up with a vastly different concensus when I come back, but hopefully not ;-) Thanks. [Reference] *1* https://lore.kernel.org/git/xmqqbl86qtyf.fsf@gitster.g/
Junio C Hamano <gitster@pobox.com> writes: > "brian m. carlson" <sandals@crustytoothpaste.net> writes: > >> I agree that in many cases we can effectively rephrase to avoid needing >> to do this, but if we acknowledge that sometimes we will need to write >> using third-person personal pronouns in some cases, it's worth >> documenting what those should be. > > I think we've heard enough from both sides and there probably is not > misunderstanding among the folks, even though there are differences > of opinions. > > I would like to consider that the last draft I did [*1*] based on > earlier suggestions by Derrick and Ævar would be a reasonable middle > ground. > > I'll go mostly offline next week---I'd notice if the list came up > with a vastly different concensus when I come back, but hopefully > not ;-) Well, I misspoke. If the list reached a consensus while I was away, then that would have been a happy outcome, whether it was close to, or vastly different from, the one I suggested. In any case, I haven't even started to try catching up with the list traffic last week, so hopefully I'll see soon enough what you folks decided (or not). > Thanks. > > > [Reference] > > *1* https://lore.kernel.org/git/xmqqbl86qtyf.fsf@gitster.g/
Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: > > > "brian m. carlson" <sandals@crustytoothpaste.net> writes: > > > >> I agree that in many cases we can effectively rephrase to avoid needing > >> to do this, but if we acknowledge that sometimes we will need to write > >> using third-person personal pronouns in some cases, it's worth > >> documenting what those should be. > > > > I think we've heard enough from both sides and there probably is not > > misunderstanding among the folks, even though there are differences > > of opinions. > > > > I would like to consider that the last draft I did [*1*] based on > > earlier suggestions by Derrick and Ævar would be a reasonable middle > > ground. > > > > I'll go mostly offline next week---I'd notice if the list came up > > with a vastly different concensus when I come back, but hopefully > > not ;-) > > Well, I misspoke. If the list reached a consensus while I was away, > then that would have been a happy outcome, whether it was close to, > or vastly different from, the one I suggested. > > In any case, I haven't even started to try catching up with the list > traffic last week, so hopefully I'll see soon enough what you folks > decided (or not). I took "I think we've heard enough" as "don't discuss about this anymore". And judging from the lack of responses from oher people I think others did interpret it in a similar vein. I still haven't seen a single argument as to why the fixes in the wording have to be necessarily tied to an update in the guidelines, so I don't see why would have changed my mind. They are orthogonal.
On 6/28/2021 6:32 PM, Junio C Hamano wrote: > Junio C Hamano <gitster@pobox.com> writes: >> I would like to consider that the last draft I did [*1*] based on >> earlier suggestions by Derrick and Ævar would be a reasonable middle >> ground. >> >> I'll go mostly offline next week---I'd notice if the list came up >> with a vastly different concensus when I come back, but hopefully >> not ;-) > > Well, I misspoke. If the list reached a consensus while I was away, > then that would have been a happy outcome, whether it was close to, > or vastly different from, the one I suggested. I hope that my reply to your attempt was clear that I found it to be a good approach. I'm happy with it. Thanks, -Stolee
On Mon, Jun 28 2021, Derrick Stolee wrote: > On 6/28/2021 6:32 PM, Junio C Hamano wrote: >> Junio C Hamano <gitster@pobox.com> writes: >>> I would like to consider that the last draft I did [*1*] based on >>> earlier suggestions by Derrick and Ævar would be a reasonable middle >>> ground. >>> >>> I'll go mostly offline next week---I'd notice if the list came up >>> with a vastly different concensus when I come back, but hopefully >>> not ;-) >> >> Well, I misspoke. If the list reached a consensus while I was away, >> then that would have been a happy outcome, whether it was close to, >> or vastly different from, the one I suggested. > > I hope that my reply to your attempt was clear that I found it to > be a good approach. I'm happy with it. Since you posted the v3 of this patch series there's been on the order of 30 E-Mails dowthread of v3 4/4, but your only replies have been to Junio. What phrasing (if any) we use for prose guidelines in the CodingGuidelines doesn't cover the various outstanding questions. Mostly point-by-point feedback from myself & Felipe. Per my upthread [1] do you plan to address that feedback & re-roll, or ignore it? 1. https://lore.kernel.org/git/87a6nryt51.fsf@evledraar.gmail.com/
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.