search

StyleGuides / WritingStyleGuide

The official Red Hat guide to writing clear, concise, and consistent technical documentation.
Creative Commons Attribution Share Alike 4.0 International
71 stars 19 forks source link

Update note about inclusive language? #489

Closed daobrien closed 1 year ago

daobrien commented 1 year ago

See https://docs.podman.io/en/latest/markdown/podman-run.1.html#footnotes

Notice how it recognizes that some language used is still problematic, but changing it would put it out of sync with underlying code and possibly lead to confusion. We'd probably do well to include something similar.

CBID2 commented 1 year ago

Hello. Based on my observations, DEI has been a major issue in the open source community, so I highly recommend making this change @daobrien. Doing this would make contributors especially those who are of African descent feel at ease(seeing the master made me uncomfortable when I first saw it). I’d love to work on this issue @daobrien! :)

daobrien commented 1 year ago

Hello. Based on my observations, DEI has been a major issue in the open source community, so I highly recommend making this change @daobrien. Doing this would make contributors especially those who are of African descent feel at ease(seeing the master made me uncomfortable when I first saw it). I’d love to work on this issue @daobrien! :)

That's great to hear~! CC'ing @julian-cable who's coordinating issues with the Style Guide now.

CBID2 commented 1 year ago

Hello. Based on my observations, DEI has been a major issue in the open source community, so I highly recommend making this change @daobrien. Doing this would make contributors especially those who are of African descent feel at ease(seeing the master made me uncomfortable when I first saw it). I’d love to work on this issue @daobrien! :)

That's great to hear~! CC'ing @julian-cable who's coordinating issues with the Style Guide now.

Thanks

julian-cable commented 1 year ago

I agree with this suggestion and would be happy to implement it. The style guide already has an Inclusive Language section, which includes a paragraph about avoiding the terms "master" and "slave": https://stylepedia.net/style/6.0/#inclusive-language

I could add a paragraph such as the following one after that paragraph (based on the Podman footnote): "Red Hat is committed to inclusivity, a core value of open source. The master and slave terminology that is used in Linux is problematic and divisive, and needs to be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Red Hat will follow suit immediately."

julian-cable commented 1 year ago

@CBID2 Would be happy to get your thoughts or suggestions about the content to add here.

CBID2 commented 1 year ago

@CBID2 Would be happy to get your thoughts or suggestions about the content to add here.

Hi @julian-cable! :) I have seen other projects use main to name the central branch. Perhaps, we can add something like this: Original: "The master and slave mount propagation terminology used here is problematic and divisive, and needs to be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time" Revised: "The master and slave mount propagation terminology used here is problematic and divisive, and needs to be changed. Consequently, we, at Linux Kernel has decided to name the branch "main" per Github's announcement." How does that sound?

julian-cable commented 1 year ago

Thanks @CBID2! I agree about using main for the central branch. Thinking about integrating this into the existing paragraph in the style guide, how about: "Do not use "master" when it is paired with "slave"." [existing text] "The master and slave mount propagation terminology that is used in Linux is problematic and divisive, and needs to be changed. For the default branch name for a GitHub repository, use "main" instead of "master"."

CBID2 commented 1 year ago

Thanks @CBID2! I agree about using main for the central branch. Thinking about integrating this into the existing paragraph in the style guide, how about:

"Do not use "master" when it is paired with "slave"." [existing text]

"The master and slave mount propagation terminology that is used in Linux is problematic and divisive, and needs to be changed. For the default branch name for a GitHub repository, use "main" instead of "master"."

I like that one @julian-cable. Shall I go make the pull request now?

julian-cable commented 1 year ago

@CBID2 Yes, please do make a pull request. Thanks!

CBID2 commented 1 year ago

@CBID2 Yes, please do make a pull request. Thanks!

@julian-cable, I can't find the repo for docs.podman. Can you link it please?

julian-cable commented 1 year ago

@CBID2 The repo in scope here for this update is the Red Hat Technical Writing Style Guide, not Podman: https://github.com/StyleGuides/WritingStyleGuide

CBID2 commented 1 year ago

@CBID2 The repo in scope here for this update is the Red Hat Technical Writing Style Guide, not Podman:

https://github.com/StyleGuides/WritingStyleGuide

Ahh thanks

CBID2 commented 1 year ago

@CBID2 The repo in scope here for this update is the Red Hat Technical Writing Style Guide, not Podman: https://github.com/StyleGuides/WritingStyleGuide

Ahh thanks

Done @julian-cable! Here’s my PR. Also, check out this issue

CBID2 commented 1 year ago

I think this issue needs to be closed now @julian-cable. Also, given the sensitivity of this issue, it's imperative to add my name as an assignee. It'll signal to other contributors, especially those from the Black community, that this repository takes inclusion seriously, as opposed to using it to bait said contributors.

julian-cable commented 1 year ago

Thanks @CBID2 for your participation here! Added you as a assignee and closing the issue now.