Re: [PATCH v2 0/4] Use singular "they" when appropriate

Derrick Stolee <stolee@gmail.com> writes:

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.