Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxx/
would be sufficient.
Thanks.
