You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: sig-architecture/naming/language-evaluation-framework.md
+21-25Lines changed: 21 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,24 +9,23 @@ The framework was created for an open source technology project. The framework m
9
9
10
10
## Using the framework
11
11
12
-
The framework is divided into three sections: first-, second-, and third-order concerns, ranked in order of potential harm to the community.
12
+
The framework is divided into three sections: first-, second-, and third-order concerns, ranked in order of potential harm to the community.
13
13
14
14
First-order concerns are language where harm is egregious, overt, and clearly problematic. Second-order concerns are language which is problematic but with a less definite impact. Third-order concerns indicate language that could use improvement but does no demonstrable harm.
15
15
16
16
Answer all questions for each term evaluated.
17
17
18
+
When complete, consider questions answered in the affirmative: in general, the more questions answered “yes” or “possibly”, the more likely it is that the language in question needs to be replaced.
18
19
19
-
When complete, consider questions answered in the affirmative: in general, the more questions answered “yes” or “possibly”, the more likely it is that the language in question needs to be replaced.
20
+
If any first-order concerns are a “yes”, replace the language.
20
21
21
-
If any first-order concerns are a “yes”, replace the language.
22
-
23
-
If a significant number of second- or third- order concerns are a “yes”, strongly consider replacing the language.
22
+
If a significant number of second- or third- order concerns are a “yes”, strongly consider replacing the language.
24
23
25
24
This framework is intentionally non-prescriptive. The intention in this work is to reduce harm for the community; let harm reduction guide your decisions.
26
25
27
26
### First-order concerns
28
27
29
-
First-order concerns are characterized by:
28
+
First-order concerns are characterized by:
30
29
31
30
- Overtness: regardless of its use in the context of code or technology, there is little to no ambiguity outside of technology as to whether the language in question indicates harm
32
31
- Identity-specificity: language in question specifically unambiguously identifies a group of people
@@ -37,19 +36,19 @@ Examples include “master/slave”.
37
36
38
37
#### Is the term overtly sexist, transphobic, or pejorative about a gender identity?
39
38
40
-
Examples do _not_ include “transclusion” of dependencies, or “binary” operators.
39
+
Examples do _not_ include “transclusion” of dependencies, or “binary” operators.
41
40
42
41
#### Is the term overtly ableist, or pejorative to neurodiverse or disabled people
43
42
44
-
Examples include performing “sanity checks”.
43
+
Examples include performing “sanity checks”.
45
44
46
-
#### Is the term overtly homophobic?
45
+
#### Is the term overtly homophobic?
47
46
48
-
Examples do not include “homogenizing” or “homogenous” data.
47
+
Examples do not include “homogenizing” or “homogenous” data.
49
48
50
49
### Second-order concerns
51
50
52
-
Second-order concerns are characterized by:
51
+
Second-order concerns are characterized by:
53
52
54
53
- Ambiguity: outside the context of code or technology, language might have connotations related to harmful scenarios like war, militarization, or policing, but the actual etymology of the term is not related to harm of a specific identity
55
54
- Lack of specific identity: concerns in this category do not target specific identities, or do so in a non-overt way
@@ -62,7 +61,6 @@ Examples include “KILL” commands in Unix systems.
62
61
63
62
Examples include “marshal/unmarshal”.
64
63
65
-
66
64
### Third-order concerns
67
65
68
66
Third-order concerns are characterized by:
@@ -73,46 +71,44 @@ Third-order concerns are characterized by:
73
71
74
72
- Idiomatic: Is language unclear to someone outside a specific culture?
75
73
76
-
77
74
#### Is the term evocative instead of descriptive?
78
75
79
-
Examples include “PetSet” (evocative) versus “StatefulSet” (descriptive).
76
+
Examples include “PetSet” (evocative) versus “StatefulSet” (descriptive).
80
77
81
78
#### Is the term ambiguous?
82
79
83
-
Examples include the use of ABORT/STOP/KILL in Unix-like systems, where they map to specific behaviors, versus general usage in programming languages, where they map to different behaviors or are used interchangeably.
80
+
Examples include the use of ABORT/STOP/KILL in Unix-like systems, where they map to specific behaviors, versus general usage in programming languages, where they map to different behaviors or are used interchangeably.
84
81
85
-
## Footnotes
82
+
## Footnotes
86
83
87
84
### Changes over time
88
85
89
-
In general, strong democratic societies become more progressive and accepting as time passes. This is a feature, not a bug.
86
+
In general, strong democratic societies become more progressive and accepting as time passes. This is a feature, not a bug.
90
87
91
-
As a result, terms that were once deemed acceptable may, at some future point, be deemed unacceptable.
88
+
As a result, terms that were once deemed acceptable may, at some future point, be deemed unacceptable.
92
89
93
90
We recommend:
94
91
95
-
- Placing a date at the top of any documents/recommendations related to naming, language inclusivity, or harm reduction
92
+
- Placing a date at the top of any documents/recommendations related to naming, language inclusivity, or harm reduction
96
93
- Expecting that some of your work will need re-evaluation at a later date
97
94
- Openness to updating language as readers and cultures change
98
95
99
-
100
96
### Dealing with trolls
101
97
102
-
In the handful of months since this work began, both Kubernetes as a whole and WG Naming have dealt with a number of issues and comments from trolls. We anticipate that anyone using this document to guide their own work will receive the same kind of attention.
98
+
In the handful of months since this work began, both Kubernetes as a whole and WG Naming have dealt with a number of issues and comments from trolls. We anticipate that anyone using this document to guide their own work will receive the same kind of attention.
103
99
104
100
In Kubernetes we mostly encounter [sea lions](http://wondermark.com/1k62/) (concern trolls), who seek to legitimize debate over false concerns in order to use up contributors' energy and time.
105
101
106
-
We work with our GitHub and other moderation teams to shut down trolling behavior at the source and remove trolling content.
102
+
We work with our GitHub and other moderation teams to shut down trolling behavior at the source and remove trolling content.
107
103
108
104
In cases where it’s unclear whether the poster is a legitimate user or a troll, we direct the work back to them: because they’re clearly “legitimately interested” in this topic, we ask them to join us in the WG Naming mailing list, drafting a formal suggestion (attached to an email address and identity we can track) and suggesting replacement terminology. Most trolls do not want to put in the effort.
109
105
110
-
Rather than be discouraged by trolls, consider it a heartening sign that you are engaged in meaningful work.
106
+
Rather than be discouraged by trolls, consider it a heartening sign that you are engaged in meaningful work.
111
107
112
108
### Kudos
113
109
114
110
This work would not have come into shape without referencing the following resources freely available online. We thank the authors of these original documents for helping guide our thoughts on the topic:
115
111
116
-
-[APA Style Guide: General Principles for reducing bias](https://apastyle.apa.org/style-grammar-guidelines/bias-free-language/general-principles)
112
+
-[APA Style Guide: General Principles for reducing bias](https://apastyle.apa.org/style-grammar-guidelines/bias-free-language/general-principles)
117
113
-[Shopify Polaris Content Guidelines: Descriptive vs. Evocative names](https://polaris.shopify.com/content/naming#section-descriptive-vs-evocative-names)
118
-
-[CNET: Twitter engineers: out with the old words...](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/)
114
+
-[CNET: Twitter engineers: out with the old words...](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/)
**Last Updated**: date PR was last updated, e.g. 2020-10-16
4
+
4
5
**Status:** Accepted
5
6
6
-
## Suggested Alternatives
7
+
## Suggested Alternatives
8
+
9
+
Replacements:
7
10
8
-
Replacements:
9
11
-`new term`: description of where this term is applicable.
10
12
<anyadditionalterms>
11
13
12
14
- Make the recommendation the title of the PR. For example: "Change default repository branches from 'master' to 'main'"
13
15
- Provide a brief, 1-3 sentence summary of the reasoning for this change
14
-
- Provide alternate recommendation(s) if needed
16
+
- Provide alternate recommendation(s), if needed
15
17
16
18
## Context
17
19
18
20
- Provide information about the recommendation. Why does this proposal matter? Who does it affect? How will it help? How does it evaluate against the [language-evaluation-framework]?
19
21
20
-
## Precedents
22
+
## Precedents
21
23
22
-
Provide any research, links to PR(s) from the Kubernetes project or other communities, standards body documents, or style guides that provide precedent for this decision.
24
+
Provide any research, links to PR(s) from the Kubernetes project or other communities, standards body documents, or style guides that provide precedent for this decision.
23
25
24
26
## Impact
25
27
26
-
Link to the results of a [Hound](https://cs.k8s.io/) keyword search. What impact will this change create?
28
+
Link to the results of a [Hound](https://cs.k8s.io/) keyword search. What impact will this change create?
0 commit comments