Documentation/community/language_style.md

   1 # Language style
   2
   3 Following our [Code of Conduct](code_of_conduct.md) the project aims to
   4 be a space where people are considerate in natural language communication:
   5
   6 There are terms in computing that were probably considered benign when
   7 introduced but are uncomfortable to some. The project aims to de-emphasize
   8 such terms in favor of alternatives that are at least as expressive -
   9 but often manage to be even more descriptive.
  10
  11 ## Political Correctness
  12
  13 A common thread in discussions was that the project merely follows some
  14 fad, or that this is a "political correctness" measure, designed to please
  15 one particular "team". While the project doesn't exist in a vacuum and
  16 so there are outside influences on project members, the proposal wasn't
  17 made with the purpose of demonstrating allegiance to any given cause -
  18 except one:
  19
  20 There are people who feel uncomfortable with some terms being used,
  21 _especially_ when that use takes them out of their grave context
  22 (e.g. slave when discussing slavery) and applies them to a rather benign
  23 topic (e.g. coordination of multiple technical systems), taking away
  24 the gravity of the term.
  25
  26 That gets especially jarring when people aren't exposed to such terms
  27 in abstract sociological discussions but when they stand for real issues
  28 they encountered.
  29
  30 When having to choose between using a well-established term that
  31 affects people negatively who could otherwise contribute more happily
  32 and undisturbed or an alternative just-as-good term that doesn't, the
  33 decision should be simple.
  34
  35 ## Token gesture
  36
  37 The other major point of contention is that such decisions are a token
  38 gesture that doesn't change anything. It's true: No slave is freed
  39 because coreboot rejects the use of the word.
  40
  41 coreboot is ambitious enough as-is, in that the project offers
  42 an alternative approach to firmware, sometimes against the vested
  43 interests (and deep pockets) of the leaders of a multi-billion dollar
  44 industry. Changing the preferred vocabulary isn't another attempt at
  45 changing the world, it's one thing we do to try to make coreboot (and
  46 coreboot only) a comfortable environment for everybody.
  47
  48 ## For everybody
  49
  50 For everybody, but with a qualifier: We have certain community etiquette,
  51 and we define some behavior we don't accept in our community, both
  52 detailed in the Code of Conduct.
  53
  54 Other than that, we're trying to accommodate people: The CoC lays out
  55 that language should be interpreted as friendly by default, and to be
  56 graceful in light of accidents. This also applies to the use of terms
  57 that the project tries to avoid: The consequence of the use of such
  58 terms (unless obviously employed to provoke a reaction - in that case,
  59 please contact the arbitration team as outlined in the Code of Conduct)
  60 should be a friendly reminder. The project is slow to sanction and that
  61 won't change just because the wrong kind of words is used.
  62
  63 ## Interfacing with the world
  64
  65 The project doesn't exist in a vacuum, and that also applies to the choice
  66 of words made by other initiatives in low-level technology. When JEDEC
  67 calls the participants of a SPI transaction "master" and "slave", there's
  68 little we can do about that. We _could_ decide to use different terms,
  69 but that wouldn't make things easier but harder, because such a deliberate
  70 departure means that the original terms (and their original use) gain
  71 lots of visibility every time (so there's no practical advantage) while
  72 adding confusion, and therefore even more attention, to that situation.
  73
  74 Sometimes there are abbreviations that can be used as substitutes,
  75 and in that case the recommendation is to do that.
  76
  77 As terms that we found to be best avoided are replaced in such
  78 initiatives, we can follow up. Members of the community with leverage
  79 in such organizations are encouraged to raise the concern there.
  80
  81 ## Dealing with uses
  82
  83 There are existing uses in our documentation and code. When we decide to
  84 retire a term that doesn't mean that everybody is supposed to stop doing
  85 whatever they're doing and spend their time on purging terms. Instead,
  86 ongoing development should look for alternatives (and so this could come
  87 up in review).
  88
  89 People can go through existing code and docs and sort out older instances,
  90 and while that's encouraged it's no "stop the world" event. Changes
  91 in flight in review may still be merged with such terms intact, but if
  92 there's more work required for other reasons, we'd encourage moving away
  93 from such terms.
  94
  95 This document has a section on retired terms, presenting the rationale
  96 as well as alternative terms that could be used instead. The main goal is
  97 to be expressive: There's no point in just picking any alternative term,
  98 choose something that explains the purpose well.
  99
 100 As mentioned, missteps will happen. Point them out, but assume no ill
 101 intent for as long as you can manage.
 102
 103 ## Discussing words to remove from active use
 104
 105 There ought to be some process when terminology is brought up as a
 106 negative to avoid. Do not to tell people that "they're feeling wrong"
 107 when they have a negative reaction to certain terms, but also try to
 108 avoid being offended for the sake of others.
 109
 110 When bringing up a term, on the project's mailing list or, if you don't
 111 feel safe doing that, by contacting the arbitration team, explain what's
 112 wrong with the term and offer alternatives for uses within coreboot.
 113
 114 With a term under discussion, see if there's particular value for us to
 115 continue using the term (maybe in limited situations, like continuing
 116 to use "slave" in SPI related code).
 117
 118 Once the arbitration team considers the topic discussed completely and
 119 found a consensus, it will present a decision in a leadership meeting. It
 120 should explain why a term should or should not be used and in the latter
 121 case offer alternatives. These decisions shall then be added to this
 122 document.
 123
 124 ## Retired terminology
 125
 126 ### slave
 127
 128 Replacing this term for something else had the highest approval rating
 129 in early discussions, so it seems pretty universally considered a bad
 130 choice and therefore should be avoided where possible.
 131
 132 An exception is made where it's a term used in current standards and data
 133 sheets: Trying to "hide" the term in such cases only puts a spotlight
 134 on it every time code and data sheet are compared.
 135
 136 Alternatives: subordinate, secondary, follower