From 4f8a58e6ea2a1edfbcd9b0f55ae44005b07c3119 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Wed, 13 Dec 2023 21:55:11 +0530 Subject: [PATCH 1/9] add content for inclusive language style guide --- docs/style-guide/inclusive-language.md | 80 ++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/style-guide/inclusive-language.md diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md new file mode 100644 index 000000000..802d2acec --- /dev/null +++ b/docs/style-guide/inclusive-language.md @@ -0,0 +1,80 @@ +title: Inclusive Language style guide +Description: This style guide outlines the guideline for using inclusive languages in documentation. +--- + +# Inclusive Language + +While writing documentation we are indirectly reaching out to thousands of people all around the globe. +Thus, we must ensure that our diverse audience can connect with our information. + +## 1. Culturally inclusive language + +Certain phrases and words are commonly used in specific regions of the world. Avoid avoiding region-specific language in the documentation. +Some examples of Region Specific Language are - +- “It’s not rocket science” is commonly used in the USA, and non-US people might not be able to relate to it properly. +- Phrases written in regional languages instead of English. +- “It’s a piece of cake” is commonly used in the USA, and non-US people might not be able to relate to it properly. +- Terms like "gypsy" is considered derogatory in Romani community, "eskimo" is considered offensive in artic community. +- Terms like "tipping point" is considered offensive in African American cultures. + +## 2. Gender neutral language + +Some phrases and words target men or men/women specifically, resulting in other gender groups feeling left out while reading our documentation. Using only male pronouns also make women in technology feel excluded or overlooked. +Similarly, we should also try to include non binary group of people with our writing. +Some examples of Gender Neutral Language are - +- Using “they/them” instead of “his/him” or “she/her”. +- Using “Hello everyone” instead of “Hello guys”. +- Using “Chairperson” instead of “Chairman” or “Chairwoman”. +- Using "people", "guests" or "folks" instead of "ladies and gentlemen". +- Using "Mx" or "Ms" instead of using "Mr" or "Mrs". +- Using "humankind" instead of "mankind". +- Avoid using sterotypes such as linking "male" with "strength", "women" with "care work", "male homosexuality" with "sensitivity". + +## 3. Accessibility and Disability + +The placement of the word “People” matters a lot when it comes to writing documentation. +Using the word “People” in the beginning makes it more pleasant as the problem is not displayed in the beginning. +The phrasing of sentences should not be in a manner that depicts Ableism or discrimination against individuals with disabilities or +the assumption that people with disabilities are inferior to those without disabilitie. + +Some examples of Gender Neutral Language are - +- Using “People with a mental health condition” instead of “Mentally Unstable People”. +- Using “Deaf” instead of “Person with deafness”. +- Using "People with a disability" instead of "Disabled people". +- Using "Wheelchair Users" instead of "Wheelchair bound". +- Using "People experiencing homelessness" instead of "Homeless people" +- Avoid using derogatory terms that refer to people with disabilities like "crazy", "retarded", and "lame". +- Try using phrases like "overlook" or "ignore" instead of "turn a blind eye", or using "unheard" or "unnoticed" instead of saying "falling on deaf ears". + +## 4. Slang free language + +While framing the documentation, we must ensure that we are not including any vulgar language even if those are +included indirectly in our work. We should be mindful of inadvertently including slang words within phrases that may have unintended or inappropriate connotations. +Some examples include - +- Using “simple” or “easy" instead of “no-brainer”. +- Using "simple" or "straightforward" instead of "easy-peasy". +- Avoid using any racist, sexist, or any discriminatory language like "stupid" or "retarted". +- Using "easy" or "simple" instead of "piece of cake". +- Using "excellent" or "impressive" instead of "dope" + +## 5. Ageism free language + +When constructing the documentation, avoiding words or phrases that may disproportionately emphasize a specific age group is important, making other age groups feel excluded. +Some examples include - +- Avoid mentioning the exact age like “60 years” old. +- Using "experienced" instead of "old-timer" +- Avoid phrases like "you are too old to understand" or "you are too yound to understand" +- Using “lively” instead of “young”. +- Avoid making assumptions about a person's abilities or interests based on their age, like assuming an older adult will not be tech savvy. + +## 6. Knowledge level assumption free language + +While building the documentation, we should always assure that we don’t presume the knowledge level of the readers. +This is because if we assume that our readers are highly skilled or have advanced experience, +we might inadvertently skip explaining or linking some important concepts. Also, we should avoid labeling some steps as “easy”, +because this might make some readers question their technical abilities. +Some examples include - +- Using “fixing the navbar is good to start with” instead of “fixing the navbar is very easy”. +- Linking complex topics which most of our audience won’t be able to understand. +- Avoid using phrases like "As you already know, the Fourier series is a mathematical method used to represent periodic functions." +- Avoid including phrases like "You're probably familiar with the concept of compound interest, so I won't go into too much detail about it." From 478b30720fd60b7d35b183f3a305165a6a10362a Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:27:00 +0530 Subject: [PATCH 2/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index 802d2acec..7c617ede8 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -1,5 +1,5 @@ title: Inclusive Language style guide -Description: This style guide outlines the guideline for using inclusive languages in documentation. +Description: This style guide outlines the guideline for using inclusive language in documentation. --- # Inclusive Language From 525d962355b657d4fd865f2b6ac1657b740e202b Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:27:12 +0530 Subject: [PATCH 3/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index 7c617ede8..32dbdc39a 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -4,7 +4,7 @@ Description: This style guide outlines the guideline for using inclusive languag # Inclusive Language -While writing documentation we are indirectly reaching out to thousands of people all around the globe. +While writing documentation we are directly speaking to thousands of people all around the globe. Thus, we must ensure that our diverse audience can connect with our information. ## 1. Culturally inclusive language From c4e64d534355ed0b6da26713aae46692614a1ba2 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:27:25 +0530 Subject: [PATCH 4/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index 32dbdc39a..5c1252c87 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -9,7 +9,7 @@ Thus, we must ensure that our diverse audience can connect with our information. ## 1. Culturally inclusive language -Certain phrases and words are commonly used in specific regions of the world. Avoid avoiding region-specific language in the documentation. +Certain phrases and words are commonly used in specific regions of the world. Avoid using region-specific language in the documentation. Some examples of Region Specific Language are - - “It’s not rocket science” is commonly used in the USA, and non-US people might not be able to relate to it properly. - Phrases written in regional languages instead of English. From 8658efae549bf9b90f204895438149147d4cda23 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:27:30 +0530 Subject: [PATCH 5/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index 5c1252c87..42dd2ea63 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -11,7 +11,7 @@ Thus, we must ensure that our diverse audience can connect with our information. Certain phrases and words are commonly used in specific regions of the world. Avoid using region-specific language in the documentation. Some examples of Region Specific Language are - -- “It’s not rocket science” is commonly used in the USA, and non-US people might not be able to relate to it properly. +- “It’s not rocket science” is commonly used in the USA, and non-US people might not be able to relate to it as intended. - Phrases written in regional languages instead of English. - “It’s a piece of cake” is commonly used in the USA, and non-US people might not be able to relate to it properly. - Terms like "gypsy" is considered derogatory in Romani community, "eskimo" is considered offensive in artic community. From 891749b5171713082e69760c61ad2a332fea366c Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:27:36 +0530 Subject: [PATCH 6/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index 42dd2ea63..d2cf154fc 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -13,7 +13,7 @@ Certain phrases and words are commonly used in specific regions of the world. Av Some examples of Region Specific Language are - - “It’s not rocket science” is commonly used in the USA, and non-US people might not be able to relate to it as intended. - Phrases written in regional languages instead of English. -- “It’s a piece of cake” is commonly used in the USA, and non-US people might not be able to relate to it properly. +- “It’s a piece of cake” is commonly used in the USA, and non-US people might not be able to relate to it as intended. - Terms like "gypsy" is considered derogatory in Romani community, "eskimo" is considered offensive in artic community. - Terms like "tipping point" is considered offensive in African American cultures. From ccc2f2db37ce6e67c81beb882016d1c567828007 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:28:14 +0530 Subject: [PATCH 7/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index d2cf154fc..0f80932a7 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -48,8 +48,7 @@ Some examples of Gender Neutral Language are - ## 4. Slang free language -While framing the documentation, we must ensure that we are not including any vulgar language even if those are -included indirectly in our work. We should be mindful of inadvertently including slang words within phrases that may have unintended or inappropriate connotations. +While framing the documentation, we must ensure that we are not including any vulgar language even if those are included indirectly in our work. We should be mindful of inadvertently including slang words within phrases that may have unintended or inappropriate connotations. Some examples include - - Using “simple” or “easy" instead of “no-brainer”. - Using "simple" or "straightforward" instead of "easy-peasy". From ef3c607be46c4e5a592f4ba25433bc82b24c2303 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:28:51 +0530 Subject: [PATCH 8/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Rohit <108233235+TRohit20@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index 0f80932a7..3d10feec5 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -69,8 +69,7 @@ Some examples include - ## 6. Knowledge level assumption free language While building the documentation, we should always assure that we don’t presume the knowledge level of the readers. -This is because if we assume that our readers are highly skilled or have advanced experience, -we might inadvertently skip explaining or linking some important concepts. Also, we should avoid labeling some steps as “easy”, +This is because if we assume that our readers are highly skilled or have advanced experience, we might inadvertently skip explaining or linking some important concepts. Also, we should avoid labelling some steps as “easy”, because this might make some readers question their technical abilities. Some examples include - - Using “fixing the navbar is good to start with” instead of “fixing the navbar is very easy”. From 3d87b821a96640b2b8c5ba948bdfb46cfbaac087 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Tue, 26 Mar 2024 10:30:56 +0530 Subject: [PATCH 9/9] Update docs/style-guide/inclusive-language.md Co-authored-by: Christine Belzie <105683440+CBID2@users.noreply.github.com> --- docs/style-guide/inclusive-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/style-guide/inclusive-language.md b/docs/style-guide/inclusive-language.md index 3d10feec5..c9e118b37 100644 --- a/docs/style-guide/inclusive-language.md +++ b/docs/style-guide/inclusive-language.md @@ -43,7 +43,7 @@ Some examples of Gender Neutral Language are - - Using "People with a disability" instead of "Disabled people". - Using "Wheelchair Users" instead of "Wheelchair bound". - Using "People experiencing homelessness" instead of "Homeless people" -- Avoid using derogatory terms that refer to people with disabilities like "crazy", "retarded", and "lame". +- Avoid using derogatory terms that refer to people with disabilities like "crazy", "retarded", spaz, and "lame". - Try using phrases like "overlook" or "ignore" instead of "turn a blind eye", or using "unheard" or "unnoticed" instead of saying "falling on deaf ears". ## 4. Slang free language