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[1] 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. > The below for-show patch[2] 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. -- brian m. carlson (he/him or they/them) Toronto, Ontario, CA
Attachment:
signature.asc
Description: PGP signature
