Reorganize folder descriptions

docs/docs/development/hardware-integration/index.mdx

@@ -41,11 +41,11 @@ The shield is usually the big PCB containing all the keys.
 
 ### Why not just "keyboard"?
 
-["Composite" keyboards](../../hardware.mdx#composite) are keyboards which use a separate small PCB MCU module (e.g. _Arduino Pro Micro_) for its "brains".
-In such keyboards, the shield is a brainless shell containing all the keys, RGB LEDs, encoders etc.
+["Composite" keyboards](../../hardware.mdx#composite) are keyboards which use a separate small PCB MCU module for its "brains".
+In such keyboards, the [shield](#what-is-a-shield) is a brainless shell containing all the keys, RGB LEDs, encoders etc.
 It typically maps all of these features to a standard pin footprint, such as the Pro Micro pinout.
 
-To bring this brainless shield to life, you attach any MCU board matching the footprint.
+To bring this brainless shield to life, you attach any MCU [board](#what-is-a-board) matching the footprint.
 For instance, the _nice!nano_ is _pin-compatible_ with the _SparkFun Pro Micro RP2040_, so you can substitute either board onto the shield.
 But each board comes with its own features (MCU, flash, BLE, etc.) which must also be handled.
 
@@ -70,34 +70,46 @@ For a [self-contained keyboard](../../hardware.mdx#onboard) that includes the mi
 You can see an example for the [Planck V6](https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm/planck) board directory.
 
 With this type of keyboard, the full ZMK definition for the keyboard exists in the `<board_root>/boards/<arch>/<keyboard_name>` directory where `<board_root>` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/arm/planck/`.
-In that directory you'll have the following files, where there can be multiple `<board_name>`s, corresponding to each keyboard part for [split keyboards](../../features/split-keyboards.md):
+In that directory you'll have the following files, where there can be multiples of files with `<board_name>`s, corresponding to each keyboard part for [split keyboards](../../features/split-keyboards.md):
+
+```
+<keyboard_name>
+├── Kconfig.board
+├── Kconfig.defconfig
+├── <board_name>_defconfig
+├── <board_name>.dts
+├── <keyboard_name>.keymap
+├── board.cmake
+└── <keyboard_name>.zmk.yml
+```
+
+These files include [base Kconfig files](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html):
 
 - A `Kconfig.board` file that defines the toplevel [Kconfig](https://docs.zephyrproject.org/3.5.0/build/kconfig/index.html) items for the board, including which SoC Kconfig setting it depends on.
 - A `Kconfig.defconfig` file that sets some initial defaults when building this keyboard. This usually includes:
-  - Setting `ZMK_KEYBOARD_NAME` to a value, for the product name to be used for USB/BLE info.
-  - Setting `ZMK_USB` and/or `ZMK_BLE` for the default values for which HID transport(s) to enable by default
+  - Setting [`ZMK_KEYBOARD_NAME`](../../config/system.md#general) to a value, for the product name to be used for USB/BLE info,
+  - Setting [`ZMK_USB`](../../config/system.md#usb) and/or [`ZMK_BLE`](../../config/system.md#bluetooth) for the default values for which HID transport(s) to enable by default
+
+[Configuration files](../../config/index.md#kconfig-files) that set the visible Kconfig symbols:
+
 - A `<board_name>_defconfig` file that forces specific Kconfig settings that are specific to this hardware configuration.
   These are mostly SoC settings around the specific hardware configuration.
+
+[Devicetree files](../../config/index.md#devicetree-files):
+
 - `<board_name>.dts` which contains all the devicetree definitions[^1], including but not limited to:
-  - An `#include` line that pulls in the specific microprocessor that is used, e.g. `#include <st/f3/stm32f303Xc.dtsi>`.
-  - Kscan, matrix transform and physical layout devicetree nodes as described above
+  - An `#include` line that pulls in the specific microprocessor that is used, e.g. `#include <st/f3/stm32f303Xc.dtsi>`,
+  - Kscan, matrix transform and physical layout devicetree nodes as described above,
   - A [chosen](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including `zmk,physical-layout` property among others, where each property references the nodes defined in the file.
-- A `board.cmake` file with CMake directives for how to flash to the device.
 - A `<keyboard_name>.keymap` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs.
-- A `<keyboard_name>.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard.
 
-With these files in place, the final folder structure can look like the following for a basic non-split keyboard:
+And other miscellaneous ones:
 
-```
-<keyboard_name>
-├── Kconfig.board
-├── Kconfig.defconfig
-├── board.cmake
-├── <board_name>.dts
-├── <board_name>_defconfig
-├── <keyboard_name>.keymap
-└── <keyboard_name>.zmk.yml
-```
+- A `board.cmake` file with CMake directives for how to flash to the device.
+- A `<keyboard_name>.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard.
+
+See Zephyr's [board porting guide](https://docs.zephyrproject.org/3.5.0/hardware/porting/board_porting.html) for information on creating a new board.
+Also see the [new keyboard shield guide](new-shield.mdx#shield-overlays) for information on parts of the devicetree specifically related to ZMK.
 
 [^1]:
     Parts of these files can live in separate `.dtsi` files (typically in the same directory) that are then `#include`d in the files, to reduce duplication or improve organization.
@@ -112,24 +124,30 @@ This allows users to swap in different boards that use the same interconnect (e.
 With this type of keyboard, the partial definition for the keyboard exists in the `<board_root>/boards/shields/<keyboard_name>` directory where `<board_root>` is `zmk/app` or a [module](../../features/modules.mdx) root, e.g. `zmk/app/boards/shields/clueboard_california/`.
 In that directory, you'll have the following files, where there can be multiple `<shield_name>`s, corresponding to each keyboard part for [split keyboards](../../features/split-keyboards.md):
 
+```
+<keyboard_name>
+├── Kconfig.shield
+├── Kconfig.defconfig
+├── <shield_name>.overlay
+├── <keyboard_name>.keymap
+└── <keyboard_name>.zmk.yml
+```
+
+These files include [base Kconfig files](new-shield.mdx#base-kconfig-files):
+
 - A `Kconfig.shield` that defines the toplevel Kconfig value for the shield, which uses a supplied utility to function to default the value based on the shield list, e.g. `def_bool $(shields_list_contains,clueboard_california)`.
 - A `Kconfig.defconfig` file to set default values for settings like `ZMK_KEYBOARD_NAME`
+
+[Devicetree files](../../config/index.md#devicetree-files):
+
 - A `<shield_name>.overlay` file which is a devicetree overlay file[^1], containing definitions including but not limited to:
   - Kscan, matrix transform and physical layout devicetree nodes as described above, where the kscan node uses the interconnect [nexus node](https://docs.zephyrproject.org/3.5.0/hardware/porting/shields.html#gpio-nexus-nodes) aliases such as `&pro_micro` for GPIO pins.
   - A [chosen](https://docs.zephyrproject.org/3.5.0/build/dts/intro-syntax-structure.html#aliases-and-chosen-nodes) node including at least the `zmk,physical-layout` property, referring to the defined node.
 - A `<keyboard_name>.keymap` file that includes the default keymap for that keyboard. Users will be able to override this keymap in their user configs.
-- A `<keyboard_name>.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard.
 
-With these files in place, the final folder structure can look like the following for a basic non-split keyboard:
+And other miscellaneous ones:
 
-```
-<keyboard_name>
-├── Kconfig.defconfig
-├── Kconfig.shield
-├── <keyboard_name>.keymap
-├── <keyboard_name>.zmk.yml
-└── <shield_name>.overlay
-```
+- A `<keyboard_name>.zmk.yml` file containing [metadata](hardware-metadata-files.md) for the keyboard.
 
 See the [new keyboard shield guide](new-shield.mdx) for documentation that walks you through creating these files to define a new composite keyboard.