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. -- Felipe Contreras
