Derrick Stolee <stolee@xxxxxxxxx> writes:
> My general approach (as specified in this v2) is:
>
> 1. Use singular "they" over "he" or "she" and other variants.
> 2. If you don't want to write "they", then avoid third-person
> singular pronouns.
>
> Your approach focuses only on item 2, giving this recommendation:
>
> * Avoid third-person singular pronouns.
>
> I think your change to CodingGuidelines is a bit verbose to get to
> that point, and makes it difficult to understand one goal is to
> avoid gendered pronouns, which I think reduces the chance that a
> new contributor would discover and understand that recommendation.
Is it fair to say that a concise summary of this discussion so far
is:
- Avoiding gendered pronous is a good way to ensure inclusive
documentation.
- Our documentation does not have too many instances of "gendered
pronouns" issue, and all of them can be corrected without
resorting to singular "they" (to which those who learned in some
parts of the world may not be ready yet), and it results in more
concise and clearer description anyway.
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. One thing
that the "let's use they" approach does better is that it brings the
"gender neutral" concern upfront, exactly because "let's make sure
the document is easier to read by everybody" is a superset and does
not have to bother singling out the "gender" as an issue.
It may be easier to move the discussion forward if we (half)
separated the concerns.
Because the "gender neutral" is so out of place relative to the
existing guidelines that focus on ensuring consistency that appear
in the "Writing Documentation" section, it is hard to make it into a
single bullet item among many others. Perhaps we want to have a new
paragraph between "mixes US and UK English" and "Every user-visible
change" paragraphs.
In order to ensure the documentation appears to be inclusive,
avoid assuming that an unspecified "cast" who appears in
description and examples is male or female, and think twice
after writing "he", "him", "she", or "her". Here are some tips
to avoid use of gendered pronouns:
- Rethink if your example or description needs to talk about a
human "cast" in the first place. Do you need to say "The
programmer chooses between X and Y as she sees fit", or is it
sufficient to say "Valid choices are X and Y" to make the
resulting sentence more concise and clear?
- If you need to talk about human "cast", think if the role the
cast plays can be second person (e.g. "If you want X to
happen, you'd pass option Y", instead of "If the user wants X
to happen, she'd ..."), or can be more than one person
(e.g. "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 talk about a human "cast" that is
third-person singluar, you may resort to "singular they" (e.g.
"A contributor asks their upstream to pull from them"). Note
however that this sounds ungrammatical and unnatural to those
who learned English as a second language in some parts of the
world.
If we were to go that route, I think the first two points (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. Also,
I do not mind losing "Note however" from the third point, but in the
name of inclusive documentation, it may not be a bad idea to remind
ourselves.
