On 6/16/2021 1:06 AM, Junio C Hamano wrote:
> 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?
...
> + - 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.
I wasn't a huge fan of this "example first" approach, but you did
a good job of tying it to the purpose and the rest of the
recommendations.
> + - 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.
This version looks good to me. It is probably worth adding Ævar in
a Co-authored-by line.
Thanks,
-Stolee
