summaryrefslogtreecommitdiff
path: root/Documentation/community/language_style.md
blob: 97f9601286d2e9d184bc3e950bdb65bccdd61911 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# Language style

Following our [Code of Conduct](code_of_conduct.md) the project aims to
be a space where people are considerate in natural language communication:

There are terms in computing that were probably considered benign when
introduced but are uncomfortable to some. The project aims to de-emphasize
such terms in favor of alternatives that are at least as expressive -
but often manage to be even more descriptive.

## Political Correctness

A common thread in discussions was that the project merely follows some
fad, or that this is a "political correctness" measure, designed to please
one particular "team". While the project doesn't exist in a vacuum and
so there are outside influences on project members, the proposal wasn't
made with the purpose of demonstrating allegiance to any given cause -
except one:

There are people who feel uncomfortable with some terms being used,
_especially_ when that use takes them out of their grave context
(e.g. slave when discussing slavery) and applies them to a rather benign
topic (e.g. coordination of multiple technical systems), taking away
the gravity of the term.

That gets especially jarring when people aren't exposed to such terms
in abstract sociological discussions but when they stand for real issues
they encountered.

When having to choose between using a well-established term that
affects people negatively who could otherwise contribute more happily
and undisturbed or an alternative just-as-good term that doesn't, the
decision should be simple.

## Token gesture

The other major point of contention is that such decisions are a token
gesture that doesn't change anything. It's true: No slave is freed
because coreboot rejects the use of the word.

coreboot is ambitious enough as-is, in that the project offers
an alternative approach to firmware, sometimes against the vested
interests (and deep pockets) of the leaders of a multi-billion dollar
industry. Changing the preferred vocabulary isn't another attempt at
changing the world, it's one thing we do to try to make coreboot (and
coreboot only) a comfortable environment for everybody.

## For everybody

For everybody, but with a qualifier: We have certain community etiquette,
and we define some behavior we don't accept in our community, both
detailed in the Code of Conduct.

Other than that, we're trying to accommodate people: The CoC lays out
that language should be interpreted as friendly by default, and to be
graceful in light of accidents. This also applies to the use of terms
that the project tries to avoid: The consequence of the use of such
terms (unless obviously employed to provoke a reaction - in that case,
please contact the arbitration team as outlined in the Code of Conduct)
should be a friendly reminder. The project is slow to sanction and that
won't change just because the wrong kind of words is used.

## Interfacing with the world

The project doesn't exist in a vacuum, and that also applies to the choice
of words made by other initiatives in low-level technology. When JEDEC
calls the participants of a SPI transaction "master" and "slave", there's
little we can do about that. We _could_ decide to use different terms,
but that wouldn't make things easier but harder, because such a deliberate
departure means that the original terms (and their original use) gain
lots of visibility every time (so there's no practical advantage) while
adding confusion, and therefore even more attention, to that situation.

Sometimes there are abbreviations that can be used as substitutes,
and in that case the recommendation is to do that.

As terms that we found to be best avoided are replaced in such
initiatives, we can follow up. Members of the community with leverage
in such organizations are encouraged to raise the concern there.

## Dealing with uses

There are existing uses in our documentation and code. When we decide to
retire a term that doesn't mean that everybody is supposed to stop doing
whatever they're doing and spend their time on purging terms. Instead,
ongoing development should look for alternatives (and so this could come
up in review).

People can go through existing code and docs and sort out older instances,
and while that's encouraged it's no "stop the world" event. Changes
in flight in review may still be merged with such terms intact, but if
there's more work required for other reasons, we'd encourage moving away
from such terms.

This document has a section on retired terms, presenting the rationale
as well as alternative terms that could be used instead. The main goal is
to be expressive: There's no point in just picking any alternative term,
choose something that explains the purpose well.

As mentioned, missteps will happen. Point them out, but assume no ill
intent for as long as you can manage.

## Discussing words to remove from active use

There ought to be some process when terminology is brought up as a
negative to avoid. Do not to tell people that "they're feeling wrong"
when they have a negative reaction to certain terms, but also try to
avoid being offended for the sake of others.

When bringing up a term, on the project's mailing list or, if you don't
feel safe doing that, by contacting the arbitration team, explain what's
wrong with the term and offer alternatives for uses within coreboot.

With a term under discussion, see if there's particular value for us to
continue using the term (maybe in limited situations, like continuing
to use "slave" in SPI related code).

Once the arbitration team considers the topic discussed completely and
found a consensus, it will present a decision in a leadership meeting. It
should explain why a term should or should not be used and in the latter
case offer alternatives. These decisions shall then be added to this
document.

## Retired terminology

### slave

Replacing this term for something else had the highest approval rating
in early discussions, so it seems pretty universally considered a bad
choice and therefore should be avoided where possible.

An exception is made where it's a term used in current standards and data
sheets: Trying to "hide" the term in such cases only puts a spotlight
on it every time code and data sheet are compared.

Alternatives: subordinate, secondary, follower