git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com>,
	git@vger.kernel.org, sandals@crustytoothpaste.net,
	stolee@gmail.com, jrnieder@gmail.com, emilyshaffer@google.com,
	Andrei Rybak <rybak.a.v@gmail.com>,
	Felipe Contreras <felipe.contreras@gmail.com>,
	Robert Karszniewicz <avoidr@posteo.de>, Jeff King <peff@peff.net>,
	"Kerry, Richard" <richard.kerry@atos.net>,
	Phillip Susi <phill@thesusis.net>,
	Johannes Schindelin <Johannes.Schindelin@gmx.de>,
	Bagas Sanjaya <bagasdotme@gmail.com>,
	Derrick Stolee <derrickstolee@github.com>,
	Derrick Stolee <dstolee@microsoft.com>
Subject: Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they
Date: Wed, 16 Jun 2021 21:54:20 +0200	[thread overview]
Message-ID: <87bl85y15s.fsf@evledraar.gmail.com> (raw)
In-Reply-To: <xmqqbl86qtyf.fsf@gitster.g>


On Wed, Jun 16 2021, Junio C Hamano wrote:

> Junio C Hamano <gitster@pobox.com> 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@evledraar.gmail.com/
>>
>> 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

That mostly-my-draft was hastily a written one-off, perhaps this is
better and a more exhaustive discussion of common cases:

  - Discussing command-line options, and program functionality:

    Prefer succinctness and matter-of-factly describing functionality in
    the abstract.  E.g.

     --short:: Emit output in the short-format.

    Avoid more verbose constructions, such as:

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

  - Addressing the reader:

    Address the reader of the documentation directly with "you",
    e.g. "you can do xyz".

  - Discussing Git, "the command" etc.:

    Use "we" when discussing how the program might react to the user, or
    perhaps "git" or "the command", e.g.:

        we might store the data[...]
        git will emit[...]
        the command will[...]

  - Discussing other users:

    When referring to other users on the same system prefer talking
    about "a user" or "another user". There's usually no reason to
    invent a cast of characters with names, titles and hobbies.

    Your OS's users don't cleanly map onto any particular people, a user
    of git might be having a merge conflict with another person, or an
    automated commit from a cron daemon.

    We prefer the style typical of standard library adn system tooling
    documentation in this and most other cases, you can look at the
    documentation of chmod(2) and other commands, syscalls and libraries
    that deal with UIDs or GIDs for examples.

  - Discussing other systems:

    As with discussing other users, git might interact with other
    systems over the network. In these cases we also avoid a cast of
    characters, preferring to talk about concepts like "fetching data
    from a remote", having a conflict with "diverging histories" etc.

The references to "gendered prounouns" etc. are gone, perhaps there's a
good reason to re-include them, but the point of "isn't that issue
solved by recommending an orthagonal approach?" is one of the many
things Stolee hasn't been addressing in the threads related to this
series.

To me that whole approach is somewhere between a solution in search of a
problem and a "let's fix it and move on". Not something we need
explicitly carry in our CodingGuidelines forever.

The v1 of this series started with decreeing that nobody should be using
gendered language in commit messages. It seems that the discussion I
started that perhaps that was overly pedantic and unfriendly to people
struggling with English won out, so that's gone in recent revisions.

That's left only a handful of examples \b(?:she|he)\b in our docs, we
have outstanding patches to fix those, and draft guidelines (amended
above) to thoroughly lead documentation writers in other directions.

It just seems superfluous to me to insist on enumerating increasingly
obscure and disfavored alternatives to what we suggest as preferred
prose in our documentation. For example, we have around the same order
of magnitude of "one might" in Documentation/, I think we should
probably just fix that and move on, not forever have a guideline against
overly formal or "Shakespearean language" in the guidelines.

  parent reply	other threads:[~2021-06-16 21:01 UTC|newest]

Thread overview: 124+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-06-07 16:57 [PATCH 0/4] Use singular "they" when appropriate Derrick Stolee via GitGitGadget
2021-06-07 16:57 ` [PATCH 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
2021-06-07 17:09   ` Ævar Arnfjörð Bjarmason
2021-06-07 17:32     ` Derrick Stolee
2021-06-07 17:42       ` Andrei Rybak
2021-06-07 18:21       ` Ævar Arnfjörð Bjarmason
2021-06-10  7:44     ` Johannes Schindelin
2021-06-10 14:35       ` Felipe Contreras
2021-06-07 21:36   ` Felipe Contreras
2021-06-09 18:47     ` Phillip Susi
2021-06-09 20:26       ` Felipe Contreras
2021-06-11 15:40         ` Phillip Susi
2021-06-11 17:03           ` Felipe Contreras
2021-06-10 18:30       ` Derrick Stolee
2021-06-11  0:16         ` Junio C Hamano
2021-06-11 16:00         ` Felipe Contreras
2021-06-12 14:02         ` Phillip Susi
2021-06-08  1:18   ` Junio C Hamano
2021-06-08  8:51     ` Kerry, Richard
2021-06-08 23:21       ` Junio C Hamano
2021-06-09 13:13         ` Derrick Stolee
2021-06-10  3:11         ` Junio C Hamano
2021-06-08 17:33   ` Emily Shaffer
2021-06-08 18:03     ` Felipe Contreras
2021-06-09 13:44       ` Kerry, Richard
2021-06-09 17:44         ` Felipe Contreras
2021-06-25 14:30           ` Kerry, Richard
2021-06-09  4:48     ` Junio C Hamano
2021-06-10  8:18     ` Johannes Schindelin
2021-06-10 14:42       ` Felipe Contreras
2021-06-14 22:10       ` Robert Karszniewicz
2021-06-07 16:57 ` [PATCH 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
2021-06-07 17:12   ` Ævar Arnfjörð Bjarmason
2021-06-07 17:20     ` Derrick Stolee
2021-06-10  8:20     ` Johannes Schindelin
2021-06-07 19:02   ` Junio C Hamano
2021-06-07 21:44     ` Felipe Contreras
2021-06-08 17:36   ` Emily Shaffer
2021-06-07 16:57 ` [PATCH 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-08 17:37   ` Emily Shaffer
2021-06-10  8:36   ` Johannes Schindelin
2021-06-10 19:53     ` Derrick Stolee
2021-06-11  9:55       ` Johannes Schindelin
2021-06-07 16:57 ` [PATCH 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-07 18:31   ` Ævar Arnfjörð Bjarmason
2021-06-08  1:47     ` Felipe Contreras
2021-06-07 18:56   ` Junio C Hamano
2021-06-07 19:05     ` Derrick Stolee
2021-06-08  0:05       ` Junio C Hamano
2021-06-10 21:34       ` brian m. carlson
2021-06-10  8:39     ` Johannes Schindelin
2021-06-07 20:00   ` Felipe Contreras
2021-06-09 18:29     ` Phillip Susi
2021-06-09 20:18       ` Felipe Contreras
2021-06-07 20:20   ` Robert Karszniewicz
2021-06-07 22:18     ` Felipe Contreras
2021-06-08  7:10   ` Jeff King
2021-06-08  8:11     ` Felipe Contreras
2021-06-09 13:23       ` Derrick Stolee
2021-06-09 15:20         ` Felipe Contreras
2021-06-10 22:06     ` brian m. carlson
2021-06-11 16:11       ` Felipe Contreras
2021-06-08 17:39   ` Emily Shaffer
2021-06-09  4:44     ` Junio C Hamano
2021-06-09 13:27       ` Derrick Stolee
2021-06-07 20:10 ` [PATCH 0/4] Use singular "they" when appropriate Felipe Contreras
2021-06-09 13:54 ` [PATCH v2 " Derrick Stolee via GitGitGadget
2021-06-09 13:54   ` [PATCH v2 1/4] Documentation: use singular they " Derrick Stolee via GitGitGadget
2021-06-09 15:33     ` Felipe Contreras
2021-06-09 13:54   ` [PATCH v2 2/4] *: use singular they in comments Derrick Stolee via GitGitGadget
2021-06-09 15:41     ` Felipe Contreras
2021-06-09 13:54   ` [PATCH v2 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-09 13:54   ` [PATCH v2 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-09 15:50     ` Felipe Contreras
2021-06-09 15:44   ` [PATCH v2 0/4] Use singular "they" when appropriate Ævar Arnfjörð Bjarmason
2021-06-09 17:22     ` Felipe Contreras
2021-06-10  2:03     ` Junio C Hamano
2021-06-10  2:28       ` Junio C Hamano
2021-06-10  3:30       ` Felipe Contreras
2021-06-10 22:32     ` brian m. carlson
2021-06-10 22:58       ` Ævar Arnfjörð Bjarmason
2021-06-11 16:32         ` Felipe Contreras
2021-06-11 17:18         ` Derrick Stolee
2021-06-11 20:38           ` Felipe Contreras
2021-06-13  7:17           ` Ævar Arnfjörð Bjarmason
2021-06-15  6:02             ` Junio C Hamano
2021-06-15 13:36               ` Derrick Stolee
2021-06-15 17:03                 ` Felipe Contreras
2021-06-14  0:47           ` Junio C Hamano
2021-06-15 14:11   ` [PATCH v3 0/4] Avoid gendered pronouns Derrick Stolee via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 1/4] doc: avoid using the gender of other people Felipe Contreras via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 2/4] comments: avoid using the gender of our users Felipe Contreras via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 3/4] *: fix typos Derrick Stolee via GitGitGadget
2021-06-15 14:11     ` [PATCH v3 4/4] CodingGuidelines: recommend singular they Derrick Stolee via GitGitGadget
2021-06-15 16:19       ` Ævar Arnfjörð Bjarmason
2021-06-15 17:26         ` Felipe Contreras
2021-06-16  2:47         ` Junio C Hamano
2021-06-16  5:06           ` Junio C Hamano
2021-06-16  9:26             ` Bagas Sanjaya
2021-06-16 17:44             ` Derrick Stolee
2021-06-16 19:54             ` Ævar Arnfjörð Bjarmason [this message]
2021-06-16 23:22               ` Felipe Contreras
2021-06-17  0:09               ` Junio C Hamano
2021-06-17 13:22                 ` Derrick Stolee
2021-06-17 14:53                   ` Ævar Arnfjörð Bjarmason
2021-06-17 17:06                     ` Felipe Contreras
2021-06-17 15:25                   ` Felipe Contreras
2021-06-18  0:26                   ` brian m. carlson
2021-06-18 16:12                     ` Felipe Contreras
2021-06-17 15:23                 ` Felipe Contreras
2021-06-17 15:58                 ` Ævar Arnfjörð Bjarmason
2021-06-18  0:53               ` brian m. carlson
2021-06-18  7:24                 ` Ævar Arnfjörð Bjarmason
2021-06-18 16:40                   ` Felipe Contreras
2021-06-19  7:03                 ` Junio C Hamano
2021-06-28 22:32                   ` Junio C Hamano
2021-06-29  1:31                     ` Felipe Contreras
2021-06-29  1:53                     ` Derrick Stolee
2021-06-29 12:29                       ` Ævar Arnfjörð Bjarmason
2021-06-17 15:12             ` Felipe Contreras
2021-06-17 14:46           ` Felipe Contreras
2021-06-15 17:08       ` Felipe Contreras
2021-06-12  4:40 ` [PATCH 0/4] Use singular "they" when appropriate Bagas Sanjaya
2021-06-12 14:19   ` Phillip Susi

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87bl85y15s.fsf@evledraar.gmail.com \
    --to=avarab@gmail.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=avoidr@posteo.de \
    --cc=bagasdotme@gmail.com \
    --cc=derrickstolee@github.com \
    --cc=dstolee@microsoft.com \
    --cc=emilyshaffer@google.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=gitster@pobox.com \
    --cc=jrnieder@gmail.com \
    --cc=peff@peff.net \
    --cc=phill@thesusis.net \
    --cc=richard.kerry@atos.net \
    --cc=rybak.a.v@gmail.com \
    --cc=sandals@crustytoothpaste.net \
    --cc=stolee@gmail.com \
    --subject='Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox