From: "Ævar Arnfjörð Bjarmason" <firstname.lastname@example.org> To: "brian m. carlson" <email@example.com> Cc: Derrick Stolee via GitGitGadget <firstname.lastname@example.org>, email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, Andrei Rybak <firstname.lastname@example.org>, Felipe Contreras <email@example.com>, Robert Karszniewicz <firstname.lastname@example.org>, Jeff King <email@example.com>, "Kerry, Richard" <firstname.lastname@example.org>, Derrick Stolee <email@example.com> Subject: Re: [PATCH v2 0/4] Use singular "they" when appropriate Date: Fri, 11 Jun 2021 00:58:22 +0200 [thread overview] Message-ID: <firstname.lastname@example.org> (raw) In-Reply-To: <YMKTARn368Qzsqc2@camp.crustytoothpaste.net> On Thu, Jun 10 2021, brian m. carlson wrote: > [[PGP Signed Part:Undecided]] > On 2021-06-09 at 15:44:59, Ævar Arnfjörð Bjarmason wrote: >> >> On Wed, Jun 09 2021, Derrick Stolee via GitGitGadget wrote: >> >> > Updates in v2 >> > ============= >> > >> > * Some edits were removed because they were in contrib/ or >> > Documentation/howto/ and these are now listed as exclusions in the >> > message of Patch 4. >> >> Thanks. >> >> > * Several recommendations to improve the edits in the documentation and >> > code comments were incorporated. Those who recommended these edits are >> > credited with "Helped-by" tags. >> >> I think a v2 is a bit premature with all the active discussion on the v1 >> thread, a lot of which isn't addressed by the v2 or this CL, e.g. many >> point I and others raised. >> >> My main objection of extending this to commit messages and thus making >> e.g. non-native speakers be on their toes when contributing to the >> project is gone, so that's good. >> >> I'm still not in favor of this change because I think an active >> recommendation like "Refer to an anonymous user in a gender neutral way" >> probably isn't needed if we simply document that our preferred prose is >> to avoid the issue entirely, which is the case in most of our >> documentation. > > I agree that in many cases in technical writing that the passive voice > (or another technique) may be preferable. For example, this selection > about O_TRUNC from open(2): > > If the file already exists and is a regular file and the access mode > allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to > length 0. If the file is a FIFO or terminal device file, the O_TRUNC > flag is ignored. Otherwise, the effect of O_TRUNC is unspecified. > > Who is truncating it? Who is ignoring it? Who is not specifying it? > In all three cases, the specific actor is unimportant or irrelevant, and > we're better off using the passive voice here than trying to enumerate > the actor. Exactly. The preferred prose in Git's documentation in this regard should be the same matter of fact prose found in C library, binutils etc. documentation. >> The below for-show patch shows an alternate approach that I think is >> a better direction than this series. >> >> It shows how some of the s/he|she/they/g search-replacements you did >> could IMO be better if we simply reduced the amount of prose, e.g. in >> strbuf.h changing: >> >> passes a context pointer, which can be used by the programmer of the >> callback as she sees fit. >> >> To: >> >> passes a `void *context` to the callback `fn` > > In many cases, saying less is better, I agree. If we don't need to > refer to a human being, then we don't need to consider any pronouns for > that human being. If we communicate things more simply with fewer > words, then that's clearly better overall for everyone involved. > Nobody's reading documentation for pleasure, after all. > > I do think that the recommendation that we refer to an anonymous user in > a gender-neutral way still stands, though. Sometimes we will need to > refer to the user or another human actor and that will be the most > natural way to express the idea, so we should use gender-neutral > language to do so. > > So roughly here, I'm in favor of both approaches. When do we need or even prefer to refer to a user like that? I haven't seen an example in our documentation that's actually better off because we're talking about things as if two "people" we need to invent pronouns for are interacting. Can anyone name one that'll stand up under scrutiny, i.e. once we can look at it and see if we couldn't phrase it better by avoiding the issue this series tries to address with a regex search-replacement? The diffstat of this series is only: 12 files changed, 22 insertions(+), 15 deletions(-) I've looked at all of them and I can't see one that wouldn't be better if the relevant text was changed similarly to what I've suggested upthread. That's why I don't think this proposal is useful. If we accept this series we're going to be left with an active recommendation for a pattern that's already almost nonexistent in our documentation. Perhaps that's because we're doing it 98% right already and aren't using "he" or "she" but "they" or "their". The multiple ways you can use "they" or "their" in the English language makes that hard to grep for. A lot of our "they"'s are referring e.g. to a command-line option, or "their" referring to "their arguments", as in the argv vector of a program. The skepticism about this being needed at all isn't an opinion I hold about software documentation in general, but about software in Git's problem space specifically. Git isn't something like software to track medical records or tax filings where we can make a hard assumption that the software is dealing with data from people, and thus the software's documentation might regularly expect to need to discuss such an invented cast of characters. We just have: * You: The "user" of the software. Maybe a human being, but that's usually no more assumed than the "user" of chmod(2) being a human being. * Other users, not people, but users in the UID/GID sense of the word. Describing system-local interactions that are really two operating system users interacting in terms of assuming that they map onto two people just adds confusion. Note how e.g. chmod(2) and other such documentation rightly avoids bringing people into the matter. At most it refers to "owner" or "another user" etc. * "Other users" on the network, e.g. you make a change, it conflicts with upstream. I think in all these cases saying something like: You can add data and commit it, then push it. Once you push it you might find another person has made changes on the same branch, he/she/it/they changed the same file as you, now you've got a conflict... Is worse than: When push your branch you might get a conflict with the remote's upstream branch, if merging it results in a conflict then... In such scenarios we're talking about e.g. our local state interacting with remote network state, those are ultimately commits or other data we have to deal with in some way. It's almost never important whether that data was made by a human or some automated system. Inventing a cast of characters just makes things more confusing. I think the nearest we come to rightly discussing actual people in the context of git's documentation is things like commit envelope data (names, E-Mail addresses). Even those don't cleanly map to human beings, so our documentation probably shouldn't be implying that in its prose.
next prev parent reply other threads:[~2021-06-10 23:45 UTC|newest] Thread overview: 124+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-06-07 16:57 [PATCH " 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 [this message] 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 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 \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: [PATCH v2 0/4] Use singular "they" when appropriate' \ /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