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