git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.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: Thu, 17 Jun 2021 09:09:20 +0900	[thread overview]
Message-ID: <xmqqtulxnyhb.fsf@gitster.g> (raw)
In-Reply-To: <87bl85y15s.fsf@evledraar.gmail.com> (=?utf-8?B?IsOGdmFyIEFy?= =?utf-8?B?bmZqw7Zyw7A=?= Bjarmason"'s message of "Wed, 16 Jun 2021 21:54:20 +0200")

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

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

This applies the most broadly and addresses common readability
issues, which is why I like this part the most.

>   - Addressing the reader:
>   - Discussing Git, "the command" etc.:

I am not sure if these are even worth saying, especially when we do
not explain why we recommend to do so.

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

I cannot exactly put my fingers on where this feeling comes from,
but this part appears to spend many lines to tell me very little.

For example, it is unclear why the second paragraph is there at all.
Sure, some commits may be created by a non people, but how does that
fact affect how I write the documentation?  Writing about such an
activity by non people, what are our recommendations?  The third
paragraph does not do much better.  Unless you have UNIX man pages
handy, chmod(2) may not be very easily accessible.  It feels as if
it wants to encourage descriptions without human actors, without
doing a very good job at explaining to readers why the guideline
does not want to see them in our documentation.

Unlike chmod(2) and getpwnam(3), but more like any dSCM, Git is a
tool to help inter-person communication, and at some point we will
have to talk about contributors asking their upstreams to pull their
work from their repositories.  It won't be like system calls dealing
with pure numbers.  We do not have to give them names like Alice and
Bob, but we do have to refer to repositories of these cast of
characters individually to clearly explain/describe how data flow
among them.

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

Unlike the above "other users", I have littleproblem with this part.
It however feels funny to warn against use of "cast of characters",
when the first sentence talks about "with other systems", which are
clearly not people.  Even when you are "fetching from a remote", you
are getting the result of work by "other people", so I would not
have separated "other users" and "other systems" in separate
sections.

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

This I think is the crux of the differences between you two.  I'd
love to hear Derrick's response and eventually see a middle ground
reached.

  parent reply	other threads:[~2021-06-17  0:09 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
2021-06-16 23:22               ` Felipe Contreras
2021-06-17  0:09               ` Junio C Hamano [this message]
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=xmqqtulxnyhb.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=avarab@gmail.com \
    --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=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