Readme rewrite (KinesisCorporation#222)

Author: ReFil

README.md

@@ -2,7 +2,11 @@
 
 ## Modifying the keymap
 
-There is a GUI for editing the keymap. It is available at https://kinesiscorporation.github.io/Adv360-Pro-GUI
+[The ZMK documentation](https://zmk.dev/docs) covers both basic and advanced functionality and has a table of OS compatibility for keycodes. Please note that the RGB Underglow, Backlight and Power Management sections are not relevant to the Advantage 360 Pro's custom ZMK fork. For more information see [this note](#note)
+
+There is a GUI for editing the keymap. It is available at https://kinesiscorporation.github.io/Adv360-Pro-GUI. This repository is also compatible with certain other web based ZMK keymap editors.
+
+Certain ZMK features require knowing the exact key positions in the matrix. They can be found in both image and text format [here](assets/key-positions.md)
 
 ## Building the Firmware with GitHub Actions
 
@@ -38,13 +42,13 @@ There is a GUI for editing the keymap. It is available at https://kinesiscorpora
 
 ### Cleanup
 
-The built docker container and compiled firmware files can be deleted with `make clean`.
+The built docker container and compiled firmware files can be deleted with `make clean`. This might be necessary if you updated your fork from V2.0 to V3.0 and are encountering build failures
 
 ## Flashing firmware
 
 Follow the programming instruction on page 8 of the [Quick Start Guide](https://kinesis-ergo.com/wp-content/uploads/Advantage360-Professional-QSG-v8-25-22.pdf) to flash the firmware.
 
-### briefly
+### Overview
 
 1. Extract the firmwares from the downloaded archive.
 1. Connect the left side keyboard to USB.
@@ -65,6 +69,16 @@ Follow the programming instruction on page 8 of the [Quick Start Guide](https://
 If you are upgrading from V2 to V3, and if the flashing didn't work as expected (i.e. if you are unable to pair the keyboard via Bluetooth), then consider [resetting](https://kinesis-ergo.com/support/kb360pro/#firmware-updates) both halves of the keyboard to its native state. Make sure to use the `settings-reset.uf2` file from 
 the V3 branch of this repository. After doing this, proceed with the flashing instructions above.
 
+## Changelog
+
+The changelog for both the config repo and the underlying ZMK fork that the config repo builds against can be found [here](CHANGELOG.md)
+
+## Note
+
+By default this config repository references [a customised version of ZMK](https://github.com/ReFil/zmk/tree/adv360-z3.2) with Advantage 360 Pro specific functionality and changes over [base ZMK](https://github.com/zmkfirmware/zmk). The Kinesis fork is regularly updated to bring the latest updates and changes from base ZMK however will not always be completely up to date.
+
+Whilst the Advantage 360 Pro is compatible with base ZMK some of the more advanced features will not work, and Kinesis cannot provide customer service for usage of base ZMK. Likewise the ZMK community cannot provide support for either the Kinesis keymap editor, nor any usage of the Kinesis custom fork.
+
 ## Other support
 
 Further support resources can be found on Kinesis.com:

assets/key-positions.md

@@ -0,0 +1,26 @@
+# Advantage 360 Pro key positions
+## Image
+![The key positions on the Advantage 360](key-positions.png)
+
+## Code
+```
+#define KEYS_L   0  1  2  3  4  5  6 \
+                14 15 16 17 18 19 20 \
+                28 29 30 31 32 33 34 \
+                46 47 48 49 50 51    \
+                60 61 62 63 64
+
+#define THUMBS_LEFT     35 36 \
+                           52 \
+                     65 66 67 \
+
+#define KEYS_R   7  8  9 10 11 12 13 \
+                21 22 23 24 25 26 27 \
+                39 40 41 42 43 44 45 \
+                   54 55 56 57 58 59 \
+                      71 72 73 74 75
+
+#define THUMBS_RIGHT 37 38    \
+                     53       \
+                     68 69 70 \
+                     ```