docs: touchups on the soft off information for improved clarity. (#2647)

5 files changed, 14 insertions, 1 deletions

diff --git a/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md b/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md
index d4fbe44c9e..affed12ef1 100644
--- a/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md
+++ b/docs/docs/development/hardware-integration/includes/_gpio-key-matrix.md
@@ -11,4 +11,4 @@ Here is an example for a keyboard with a GPIO pin that reads from the matrix:
 };
 ```
 
-Matrix inputs are triggered by pulling the specified pin high, typically by pressing some combination of switches which connects the matrix input to a matrix output.
+MCU inputs are triggered by pulling the specified pin high, typically by pressing some combination of switches which connects the MCU input to an MCU output.
diff --git a/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md b/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md
index 7f8995b5bc..0a02289441 100644
--- a/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md
+++ b/docs/docs/development/hardware-integration/includes/_gpio-key-wakeup.md
@@ -12,3 +12,4 @@ Here is an example for a keyboard with a GPIO pin reused from a matrix kscan:
 ```
 
 The GPIO settings should match those in the kscan, so the above would be set to `(GPIO_ACTIVE_LOW | GPIO_PULL_UP)` for a direct kscan.
+The specified pin should be the MCU input pin of the switch used for waking from soft off (for a `col2row` matrix, the MCU input pins are the row pins).
diff --git a/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md b/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md
index b4377b902e..9967f39893 100644
--- a/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md
+++ b/docs/docs/development/hardware-integration/includes/_soft-off-behavior.md
@@ -8,6 +8,7 @@ Behind the scenes, a hardware dedicated GPIO pin utilizes the [soft off behavior
         hw_soft_off: hw_soft_off {
             compatible = "zmk,behavior-soft-off";
             #binding-cells = <0>;
+            split-peripheral-off-on-press; // Turn peripheral off immediately for reliability
             hold-time-ms = <2000>; // Only turn off if the key is held for 2 seconds or longer.
         };
     };
diff --git a/docs/docs/development/hardware-integration/includes/_soft-off-waker.md b/docs/docs/development/hardware-integration/includes/_soft-off-waker.md
index 214abc970a..2bf5ffef89 100644
--- a/docs/docs/development/hardware-integration/includes/_soft-off-waker.md
+++ b/docs/docs/development/hardware-integration/includes/_soft-off-waker.md
@@ -14,3 +14,4 @@ We need to add another device which will be enabled only when the keyboard is go
 ```
 
 The properties for the `gpio-key-wakeup-trigger` node can be found in the [appropriate configuration section](../../../config/power.md#gpio-key-wakeup-trigger).
+In particular, note the `extra-gpios` property containing the MCU output pins of any keys used to wake the keyboard (for a `col2row` matrix, these are your columns).
diff --git a/docs/docs/keymaps/behaviors/soft-off.md b/docs/docs/keymaps/behaviors/soft-off.md
index d51a49255e..0b664df2e4 100644
--- a/docs/docs/keymaps/behaviors/soft-off.md
+++ b/docs/docs/keymaps/behaviors/soft-off.md
@@ -38,3 +38,13 @@ By default, the keyboard will be turned off as soon as the key bound to the beha
     };
 };
 ```
+
+The peripheral half of a [split keyboard](../../features/split-keyboards.md) will always enter the soft off state immediately when triggering the behavior, regardless of the `hold-time-ms` setting. This is to ensure reliability, as otherwise the central may enter the soft off state before notifying the peripheral that it should also do so.
+
+If you wish to change this setting, and thus accept the potential for reliability issues, you may remove the `split-peripheral-off-on-press` flag from the behavior:
+
+```dts
+&soft_off {
+    /delete-property/ split-peripheral-off-on-press;
+};
+```