Apply suggestions from code review

Co-authored-by: Cem Aksoylar <[email protected]>

docs/docs/development/hardware-integration/dongle.md

@@ -3,31 +3,31 @@ title: Keyboard Dongle
 sidebar_label: Keyboard Dongle
 ---
 
-A bluetooth dongle can be added to any keyboard running ZMK. The result is a [split keyboard](../../features/split-keyboards.md) with the dongle as "central". There are a number of advantages to adding a dongle, but also some disadvantages:
+A bluetooth dongle can be added to any keyboard running ZMK. The result is a [split keyboard](../../features/split-keyboards.md) with the dongle as ["central"](../../features/split-keyboards.md#central-and-peripheral-roles). There are a number of advantages to adding a dongle, but also some disadvantages:
 
 Benefits:
 
-- The "central" dongle results in [improved battery life](/power-profiler) for the keyboard/former "central", as it is now a peripheral.
-- It is easier to connect to the host device.
+- For split keyboards, having the dongle for the "central" role results in [improved battery life](/power-profiler) for the former central part, as it is now a peripheral.
+- It is easier to connect to the host device since dongles are typically connected via USB.
 
 Disadvantages:
 
 - An extra [board](../../faq.md#what-is-a-board) is needed (any BLE-capable board will work).
 - The keyboard becomes unusable without the dongle.
 
 Depending on how the dongle is used, there are some additional [latency considerations](../../features/split-keyboards.md#latency-considerations) to keep in mind.
-The addition of the dongle adds an extra "hop" for the former central, increasing its latency to that of a peripheral. The other parts are unchanged latency wise. There is also a commonly occurring case where the peripherals benefit.
+The addition of the dongle adds an extra "hop" for the former central, increasing its latency to that of a peripheral. The other parts are unchanged latency-wise. There is also a commonly occurring case where the peripherals benefit.
 Assuming the dongle is connected to USB and the former central would have been connected via bluetooth to the host if the dongle wasn't present:
 
 - The former central will have its latency increased by about 1ms from the extra USB "hop"
 - The other parts will have their average latency _decreased_ by 6.5ms from the replacement of a BLE "hop" with a "USB" hop.
 
-In other words, for this commonly occurring case the average latency of the keyboard actually decreases.
+As a result, for this common use case the average latency of the keyboard decreases.
 
 ## Adding a Dongle
 
 To add a dongle, you will create a simplified form of a [new shield](./new-shield.mdx).
-If you wish for your dongle to have any keys, then the below approach will not work.
+The approach described below assumes the dongle will not have any keys assigned to itself, so it will not work for that scenario.
 
 As there are a very large number of possible devices that could be used as a dongle, you will be defining your dongle as a personal shield intended for your exclusive use.
 
@@ -43,19 +43,17 @@ Next, navigate to the `zmk-config/boards/shields` directory. Create a subdirecto
 
 #### Kconfig.shield
 
-Make a file called `Kconfig.shield`, if one does not exist already. Add the following lines to it:
+Make a file called `Kconfig.shield`, if one does not exist already. Add the following lines to it, replacing `SHIELD_MY_KEYBOARD_DONGLE` and `my_keyboard_dongle` according to your keyboard:
 
 ```kconfig title="Kconfig.shield"
 # No whitespace after the comma or in the keyboard name!
 config SHIELD_MY_KEYBOARD_DONGLE
     def_bool $(shields_list_contains,my_keyboard_dongle)
 ```
 
-Note that there are _two_ names you need to adjust in the above: `SHIELD_MY_KEYBOARD_DONGLE` and `my_keyboard_dongle`.
-
 #### Kconfig.defconfig
 
-Make a file called `Kconfig.defconfig`, if one does not exist already. Add the following lines to it:
+Make a file called `Kconfig.defconfig`, if one does not exist already. Add the following lines to it where `SHIELD_MY_KEYBOARD_DONGLE` should match the previous section:
 
 ```kconfig title="Kconfig.defconfig"
 if SHIELD_MY_KEYBOARD_DONGLE
@@ -73,8 +71,6 @@ config ZMK_SPLIT
 endif
 ```
 
-Note that `SHIELD_MY_KEYBOARD_DONGLE` should be adjusted to match the previous section.
-
 ### Dongle Overlay File
 
 You will now need to find and copy your keyboard's matrix transform and physical layout. Navigate to the directory defining your keyboard (in-tree keyboards found [here](https://github.com/zmkfirmware/zmk/tree/main/app/boards)) and look through the [devicetree files](../../config/index.md) for nodes with `compatible = "zmk,matrix-transform";` or `compatible = "zmk,physical-layout";`. These should look something like this:
@@ -103,7 +99,7 @@ You will now need to find and copy your keyboard's matrix transform and physical
     };
 ```
 
-You may find some keyboards import their physical layouts from [this location](https://github.com/zmkfirmware/zmk/tree/main/app/dts/layouts).
+You may find some keyboards import their physical layouts from [this location](https://github.com/zmkfirmware/zmk/tree/main/app/dts/layouts), in which case note the `#include` lines and any nodes that modify the properties that come from the shared layout.
 
 Now that you've found these nodes, make a file called `my_keyboard_dongle.overlay` (renamed as appropriate) and add the following lines to it:
 
@@ -123,7 +119,7 @@ Now that you've found these nodes, make a file called `my_keyboard_dongle.overla
 
     // Copy of matrix transform node here
     // Copy of physical layout node here
-      // If kscan property of physical layout is present, assign &mock_kscan to it
+    //     If kscan property of physical layout is present, assign &mock_kscan to it
 };
 ```
 
@@ -176,7 +172,7 @@ CONFIG_ZMK_SPLIT_BLE_CENTRAL_PERIPHERALS=n # Change n to the number of periphera
 CONFIG_BT_MAX_CONN=m # Change m to be equal or greater than the number of peripherals + the number of bt hosts the dongle should connect to
 ```
 
-You can always remove the above lines if you wish to go back to not using a dongle.
+To go back to not using a dongle, you can undo the changes in this section by removing the corresponding lines.
 
 :::note
 Under certain conditions, you may also need to change `CONFIG_BT_MAX_CONN` when using a unibody: See the [configuration documentation](../../config/system.md#bluetooth).
@@ -199,5 +195,5 @@ include:
 ```
 
 :::warning
-Before flashing your new firmware, flash `settings_reset` [firmware](../../troubleshooting/connection-issues.mdx#acquiring-a-reset-uf2) on all devices.
+Before flashing your new firmware, you need to flash `settings_reset` [firmware](../../troubleshooting/connection-issues.mdx#acquiring-a-reset-uf2) on all devices to ensure they can pair to each other.
 :::