Junio C Hamano <gitster@xxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxx/
>
> 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
--
2.32.0-241-g31cd86ad06
