diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md
index fdad90f3..61630c84 100644
--- a/docs/integrations/matrix.md
+++ b/docs/integrations/matrix.md
@@ -268,7 +268,7 @@ Both fixed in `nix/host-modules/hive-matrix.nix` via two derivations:
   incremental cost) and (b) installs `fluffychat-web-imaging`'s
   outputs into `$out`.
 
-Two non-obvious details worth knowing before touching either derivation:
+Two subtle details worth knowing before touching either derivation:
 
 - **`make -C js`** instead of `cd js; make` — keeps the build-phase
   pwd at the source root so `installPhase` doesn't have to know
diff --git a/docs/process/conventions.md b/docs/process/conventions.md
index 2a456c53..2733f2a8 100644
--- a/docs/process/conventions.md
+++ b/docs/process/conventions.md
@@ -439,8 +439,8 @@ POST handlers both call into them so the two surfaces never drift.
 ## Commit messages
 
 Short, lowercase, no `Co-Authored-By` trailer. Imperative mood, no
-period. Body explains *why* if non-obvious; otherwise the subject
-alone is fine. Wrap at ~72 cols.
+period. Body explains *why* when the reasoning isn't self-evident;
+otherwise the subject alone is fine. Wrap at ~72 cols.
 
 ## Commit before test
 
diff --git a/docs/swarm/ca.md b/docs/swarm/ca.md
index 611bd99c..3f9d4d96 100644
--- a/docs/swarm/ca.md
+++ b/docs/swarm/ca.md
@@ -159,7 +159,7 @@ The root **key** is a runtime file for the reason in
 
 The root **certificate** is a runtime file as a _consequence_ — it lives
 beside the key under `swarm.ca.stateDir` — and that has a cost worth
-naming, because it is not obvious and it bites at a distance:
+naming, because it is subtle and it bites at a distance:
 
 > **Nothing whose trust store is assembled at build time can reference
 > the swarm root.** `security.pki.certificateFiles` is read inside the