Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Use gender-neutral pronouns in the docs. #6535

Closed
wants to merge 1 commit into from
Closed

doc: Use gender-neutral pronouns in the docs. #6535

wants to merge 1 commit into from

Conversation

majjoha
Copy link
Contributor

@majjoha majjoha commented Jul 25, 2020

This pull request replaces gendered pronouns in the documentation with gender-neutral ones. I've followed the Google developer documentation style guide on how to write gender-neutral technical documentation, and to find instances of gendered language in the documentation, I've been running the following commands:

rg '\bhe\b' runtime/doc
rg '\bhim\b' runtime/doc
rg '\bhis\b' runtime/doc
rg '\bhimself\b' runtime/doc
rg '\bshe\b' runtime/doc
rg '\bher\b' runtime/doc
rg '\bhers\b' runtime/doc
rg '\bherself\b' runtime/doc

In addition, I think the section about inclusion in runtime/doc/helphelp.txt which was added in eab6dff causes unnecessary harm, and I'd suggest that it is either removed from the documentation or updated to encourage people to create pull requests when they stumble upon gendered language in the documentation. If there is any interest in the latter, I am more than happy to help out.

@codecov
Copy link

codecov bot commented Jul 25, 2020

Codecov Report

Merging #6535 into master will decrease coverage by 0.01%.
The diff coverage is n/a.

Impacted file tree graph

@@            Coverage Diff             @@
##           master    #6535      +/-   ##
==========================================
- Coverage   88.30%   88.29%   -0.02%     
==========================================
  Files         146      146              
  Lines      159966   159966              
==========================================
- Hits       141259   141242      -17     
- Misses      18707    18724      +17     
Impacted Files Coverage Δ
src/gui.c 63.05% <0.00%> (-0.61%) ⬇️
src/netbeans.c 76.07% <0.00%> (-0.52%) ⬇️
src/gui_gtk_x11.c 58.66% <0.00%> (-0.35%) ⬇️
src/gui_gtk.c 31.44% <0.00%> (-0.28%) ⬇️
src/sign.c 94.77% <0.00%> (-0.18%) ⬇️
src/version.c 92.13% <0.00%> (ø)
src/terminal.c 91.02% <0.00%> (+0.03%) ⬆️
src/if_xcmdsrv.c 88.73% <0.00%> (+0.17%) ⬆️
src/getchar.c 86.46% <0.00%> (+0.29%) ⬆️
src/ex_getln.c 91.71% <0.00%> (+0.33%) ⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 24aa48b...0ab2563. Read the comment docs.

@brammool
Copy link
Member

brammool commented Jul 25, 2020

I find this offensive to females.

@brammool brammool closed this Jul 25, 2020
@nickspoons
Copy link

nickspoons commented Jul 25, 2020

As well as making the documentation consistent (sometimes the docs use "s/he", other times they just use "he" etc.), this PR also fixes several small grammatical errors. It seems like a good idea to include it - and it appears to be quite thorough so it will reduce more discussion on this topic - once it's done, it's done, and everyone is happy.

@majjoha
Copy link
Contributor Author

majjoha commented Jul 26, 2020

@brammool: I am not entirely sure I follow how. Would you mind elaborating on what you mean?

@brammool
Copy link
Member

brammool commented Jul 26, 2020

This deserves some more explanation, I didn't have time for that yesterday.
This pull request pretends to improve gender neutrality, but actually does the opposite.

Most obviously, it removes the statement of inclusion, that makes clear Vim was made for everybody.

More subtly, this change infers that using "he" when referring to the user means the user would be male.
This instantly creates a problem, instead of solving it. It teaches people one way of interpreting the English
language in a way that I find offensive. It's like two tribes living happily next to each other until someone
blows up a difference and causes the tribes to go to war.

Let it be clear: I am allergic to discrimination and injustice. I might be a bit sensitive about this subject.
I feel offended if people say something bad about text that was written with good intentions.

@@ -34,7 +34,7 @@ balance must be found between them.
VIM IS... VI COMPATIBLE *design-compatible*

First of all, it should be possible to use Vim as a drop-in replacement for
Vi. When the user wants to, he can use Vim in compatible mode and hardly
Vi. When the user wants to, they can use Vim in compatible mode and hardly
Copy link
Contributor

@dpelle dpelle Jul 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a native English speaker, but "he" was referring the "the user" in the first part of the sentence.
So saying "they" does not look correct.

Same remark in some other places.
I don't think we need to workaround the fact that English has no neutral he/she pronoun.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is perfectly correct to use "they" here. In fact it is more common to write "they" in this situation, as until this point the gender has not been specified.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regardless of how much people push for it, neutral 'they' doesn't feel natural when not used as a wildcard.

@vim-ml
Copy link

vim-ml commented Jul 26, 2020

@majjoha
Copy link
Contributor Author

majjoha commented Jul 26, 2020

@brammool: My intention with this pull request was not to offend you. I am a longtime Vim user and appreciate your tireless work on the text editor. However, I disagree that the changes create a situation where the documentation appears less gender-neutral than before. To me, it is unclear how insisting on using gendered pronouns promotes gender neutrality to a larger extent than using a pronoun that can be applied regardless of gender and carries less ambiguity.
While I acknowledge the fact that the text in runtime/doc/helphelp.txt was written with the best intentions, my suggestions raised in this pull request are not a criticism of you but simply of the words. This would have been the case if my pull request suggested code changes too.

Using pronouns such as "he" or "she" in the documentation both implicitly favors the given gender but perhaps more importantly it excludes the people who do not identify with either gender. This is particularly problematic in situations where the reader may identify as non-binary. IBM, Google, and Microsoft already encourage the use of singular "they" but popular open source projects such as Chromium and Ruby on Rails as well as GNU do the same, and I fail to see why this project should not follow suit.

their first language. We do not make any assumptions about the gender of the
user, no matter how the text is phrased. And we do not want to waste time on
this discussion. The goal is that the reader understands how Vim works, the
exact wording is secondary.
Copy link

@Tyil Tyil Jul 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this part being removed? It solves the very problem this PR is intending to solve, so it feels like this is being removed in order to introduce a problem, to then justify this PR. Specifically, the part "And we do not want to waste time on this discussion", which would prohibit this PR to begin with.

This PR reeks of virtue-signalling.

Copy link
Contributor Author

@majjoha majjoha Jul 29, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Tyil: I strongly disagree with your statement. I am admittedly surprised that this pull request is seen as an act of virtue signalling when it simply attempts to remove harmful language from the documentation in order to show consideration for underrepresented groups in our industry.

From my previous comments, I think it should be clear why this text does not solve the issue but let me dissect it to further stress my argument.
In the first sentence, two issues are apparent. First, it neglects how using "his" is in fact an issue of great importance to a lot of people, and, secondly, it notes that the use of "his" does not imply that the user is male as some people may think. By using "his", I think it is only natural to make this assumption. For anybody who identifies as non-male, I imagine that it may seem incredibly counterintuitive why the documentation is so hesitant to adopt singular "they" instead of gendered pronouns if this is the case. Why not simply apply a pronoun that carries no assumptions about the gender if it is so important to keep stating that there are no assumptions about the gender? Using singular "they" removes the need to do so. Then it goes on to explain that the use of "his" is just the result of a habit that has developed throughout the years. In the past, we have used hurtful words to describe various groups of people but we have shown time and time again that we can change habits for the better. I do not see why the Vim documentation should not welcome change of this form too. Finally, the text once again mentions that it "do[es] not want to waste time on this discussion" which returns to the theme of neglecting how this issue may be hugely important to a lot of people.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To support @majjoha opinion here, there are two things I would like to add about this removed part.

  • First, I came accross this text long after I had started reading the docs. I understand that this is not the way the docs are intended to be read, and that maybe I should have read it first. But I bet many people do the same. Should they feel offended by the rest of the doc, then it would be too late and it's not just "their fault". Especially now that this PR exists and that the burden of editing the whole doc has been taken in charge by @majjoha.

  • Second, even though I don't personally feel offended by this removed part. Here is how I understand/rephrase it in my head:

We are aware that the exact wording of the doc is likely to offend people. However, we think it is secondary matter so we did not intend to fix it.

.. which I feel offending.

Copy link

@mikepqr mikepqr Aug 12, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this part being removed? It solves the very problem this PR is intending to solve.

A declaration that no harm is meant is not sufficient to do no harm. It is in a place that few users of the documentation will ever see. And "you might find this offensive but I assure it is not offensive" doesn't actually help a person who feels excluded. "We don't think this is important" is even worse.

@cweagans
Copy link

cweagans commented Aug 1, 2020

It is not "perfectly correct" to use "they" here. "They" is plural and the sentence calls for a singular pronoun. I recognize that the use of "they" as a singular pronoun is becoming more common as perhaps the least-problematic solution to this problem, but it is not yet universally accepted.

"they" as a replacement for he/she (in the context of talking about a specific person) is a new use of the word, but the singular "they" as a pronoun for a single person of unknown/irrelevant gender has been in use since the 1300s.

https://apastyle.apa.org/style-grammar-guidelines/grammar/singular-they

https://en.wikipedia.org/wiki/Singular_they

https://www.merriam-webster.com/words-at-play/singular-nonbinary-they

https://public.oed.com/blog/a-brief-history-of-singular-they/

"They" is a perfectly acceptable pronoun to use in this context because we do not know or care which gender any given user is. Your lack of acceptance of the singular they as a correct grammatical construct does not mean that it is incorrect.

@cweagans
Copy link

cweagans commented Aug 1, 2020

Moreover:

More subtly, this change infers that using "he" when referring to the user means the user would be male.

This is a reasonable interpretation, given that "he" is widely used as a pronoun for male-identifying individuals?

I feel offended if people say something bad about text that was written with good intentions.

Respectfully, that's a you problem. You presumably wouldn't react this way if it were a bug report about some vim subsystem misbehaving. Consider this a bug report for a different language.

@mikepqr
Copy link

mikepqr commented Aug 12, 2020

I find the reaction to this PR extremely disappointing. I hope this PR will be merged. Changing he to singular they (which most emphatically is idiomatic English) is an easy fix.

@brammool
Copy link
Member

brammool commented Aug 13, 2020

I have been trying to get used to "the user, they..." but it just keeps sounding wrong. It's like using Shakespearean English: it may be correct English, but that's just not how you would say it in real life.
I understand some people (and I think it's actually not that many, but they are very opinionated) object to using "the user, he...". So we need to phrase that differently. It takes some more effort, but there aren't that many occurrences.
That way we can please more people.

@mikepqr
Copy link

mikepqr commented Aug 13, 2020

it may be correct English, but that's just not how you would say it in real life.

If your point is that singular they is not idiomatic spoken casual English then I have two responses:

  1. as a native English speaker who has lived in three English-speaking countries (UK, USA, Australia), your claim is empirically false.
  2. documentation for a computer program does not need to be (and is not usually) written in idiomatic spoken casual English.

If your point is that singular they is incorrect in more formal settings then please see the many authoritative links posted by @cweagans.

If you'd be interested in taking a look, I'd be happy to submit a PR that tries to "write around" the problem to avoid singular they while eliminating "he" (which is sometimes possible). Please let me know.

But honestly, this PR is fine, and I think it should be accepted.

p.s. I think that describing people who care about this issue as "very opinionated" unnecessarily implies bad faith on their part. We care about this not because we enjoy bikeshedding trivia or signalling our virtue. We care about the fact that our community and our industry has failed and hurt people.

@vim-ml
Copy link

vim-ml commented Aug 14, 2020

@lilydjwg
Copy link

lilydjwg commented Aug 14, 2020

@dkearns
Copy link
Contributor

dkearns commented Aug 14, 2020

it may be correct English, but that's just not how you would say it in real life.
[...]
1. as a native English speaker who has lived in three English-speaking countries (UK, USA, Australia), your claim is empirically false.

I concur and, as a native Australian English speaker, it is how I have always spoken and written.

I have been picked up on it a few of times over the years by those whose first language was, perhaps just coincidentally, German. Unfortunately, I have forgotten any explanation that might have been offered as to why it sounded odd to them.

@brammool
Copy link
Member

brammool commented Aug 14, 2020

Looks like we heard all opinions at least twice now.

@vim vim locked as resolved and limited conversation to collaborators Aug 14, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet