docs: Explain our shift in terminology

2 files changed, 41 insertions, 0 deletions

diff --git a/docs/design_guide.rst b/docs/design_guide.rst
index 1d40943ac..2d52e988b 100644
--- a/docs/design_guide.rst
+++ b/docs/design_guide.rst
@@ -1,3 +1,5 @@
+.. role:: strike
+
 Design Guide
 ============
 
@@ -46,6 +48,41 @@ not have the ``adafruit_`` module or package prefix.
 
 Both should have the CircuitPython repository topic on GitHub.
 
+Terminology
+-----------
+
+As our Code of Conduct states, we strive to use "welcoming and inclusive
+language." Whether it is in documentation or in code, the words we use matter.
+This means we disfavor language that due to historical and social context can
+make community members and potential community members feel unwelcome.
+
+There are specific terms to avoid except where technical limitations require it.
+While specific cases may call for other terms, consider using these suggested
+terms first:
+
++--------------------+---------------------+
+| Preferred          | Deprecated          |
++====================+=====================+
+| Main (device)      | :strike:`Master`    |
++--------------------+---------------------+
+| Peripheral         | :strike:`Slave`     |
++--------------------+                     +
+| Sensor             |                     |
++--------------------+                     +
+| Secondary (device) |                     |
++--------------------+---------------------+
+| Denylist           | :strike:`Blacklist` |
++--------------------+---------------------+
+| Allowlist          | :strike:`Whitelist` |
++--------------------+---------------------+
+
+Note that "technical limitations" refers e.g., to the situation where an
+upstream library or URL has to contain those substrings in order to work.
+However, when it comes to documentation and the names of parameters and
+properties in CircuitPython, we will use alternate terms even if this breaks
+tradition with past practice.
+
+
 .. _lifetime-and-contextmanagers:
 
 Lifetime and ContextManagers
diff --git a/docs/static/customstyle.css b/docs/static/customstyle.css
index 6c964b762..3c0bc8424 100644
--- a/docs/static/customstyle.css
+++ b/docs/static/customstyle.css
@@ -24,3 +24,7 @@
       overflow: visible !important;
    }
 }
+
+.strike {
+    text-decoration: line-through;
+}