update doc for new shield in user repo

3 files changed, 35 insertions, 1 deletions

diff --git a/docs/docs/dev-guide-new-shield.md b/docs/docs/dev-guide-new-shield.md
index 94f7d1d..b61ece9 100644
--- a/docs/docs/dev-guide-new-shield.md
+++ b/docs/docs/dev-guide-new-shield.md
@@ -27,6 +27,15 @@ ZMK support for split keyboards requires a few more files than single boards to
 
 ## New Shield Directory
 
+:::note
+This guide describes how to add shield to the ZMK main repository. If you are building firmware for your 
+own prototype or handwired keyboard, it is recommended to use your own user config repository. Follow the
+[user setup guide](./user-setup.md) to create your user config repository first. When following the rest
+of this guide, replace the `app/` directory in the ZMK main repository with the `config/` directory in your
+user config repository. Form example, `app/boards/shields/<keyboard_name>` should now be 
+`config/boards/shields/<keyboard_name>`.
+:::
+
 Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be:
 
 ```bash
@@ -66,7 +75,7 @@ that make sense to have different defaults when this shield is used. One main it
 that usually has a new default value set here is the `ZMK_KEYBOARD_NAME` value,
 which controls the display name of the device over USB and BLE.
 
-The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file:
+The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file. Note: do not make the keyboard name too long, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your laptop / tablet.
 
 ```
 if SHIELD_MY_BOARD
diff --git a/docs/docs/dev-guide-usb-logging.md b/docs/docs/dev-guide-usb-logging.md
index 7f1fad7..26706c2 100644
--- a/docs/docs/dev-guide-usb-logging.md
+++ b/docs/docs/dev-guide-usb-logging.md
@@ -50,6 +50,13 @@ CONFIG_UART_CONSOLE_ON_DEV_NAME="CDC_ACM_0"
 CONFIG_USB_UART_DTR_WAIT=n
 ```
 
+:::note
+If you are debugging your own keyboard in your [user config repository](./user-setup.md), use
+`config/boards/shields/<your_keyboard>/<your_keyboard>.conf` instead of `app/prj.conf`. In Github
+Actions, you can search the `Kconfig file` build log to verify the options above have been enabled 
+for you successfully.
+:::
+
 ## Viewing Logs
 
 After flashing the updated ZMK image, the board should expose a USB CDC ACM device that you can connect to and view the logs.
@@ -59,6 +66,7 @@ defaultValue="linux"
 values={[
 {label: 'Linux', value: 'linux'},
 {label: 'Windows', value: 'win'},
+{label: 'MacOS', value: 'macos'}
 ]}>
 <TabItem value="linux">
 
@@ -80,6 +88,17 @@ On Windows, you can use [PuTTY](https://www.putty.org/). Once installed, use Dev
 If you already have the Ardunio IDE installed you can also use its built-in Serial Monitor.
 
 </TabItem>
+<TabItem value="macos">
+
+On MacOS, the device name is something like `/dev/tty.usbmodemXXXXX` where `XXXXX` is some numerical ID. 
+You can connect to the device with [tio](https://tio.github.io/) (can be installed via [Homebrew](https://formulae.brew.sh/formula/tio)):
+
+```
+sudo tio /dev/tty.usbmodem14401
+```
+
+You should see tio printing `Disconnected` or `Connected` when you disconnect or reconnect the USB cable. 
+</TabItem>
 </Tabs>
 
 From there, you should see the various log messages from ZMK and Zephyr, depending on which systems you have set to what log levels.
diff --git a/docs/docs/user-setup.md b/docs/docs/user-setup.md
index 1e1e1e8..7f5348f 100644
--- a/docs/docs/user-setup.md
+++ b/docs/docs/user-setup.md
@@ -33,6 +33,12 @@ Following the steps in this guide, you will:
 1. Update the configuration flags for your user config, to enable/disable any ZMK features you would like to include.
 1. Commit and push the updates to trigger a new GitHub Action run.
 
+:::note
+If you are building firmware for a new keyboard shield that is not included in the built-in
+list of shields, you can choose any shield from the list that is similar to yours to generate the repository, 
+and edit / add necessary files according to the [guide for adding new keyboard shield](./dev-guide-new-shield.md).
+:::
+
 ## Prerequisites
 
 The remainder of this guide assumes the following prerequisites: