makerdiary · xiongyihui · Sep 18, 2020 · Sep 17, 2020 · Sep 17, 2020 · Sep 17, 2020
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -5,14 +5,14 @@ you do, please read the following guidelines.
 
 ## Got a question or problem?
 
-For quick questions there's no need to open an issue as you can reach us on [makerdiary/community](https://community.makerdiary.com).
+For quick questions there's no need to open an issue, because you can reach us on [makerdiary/community](https://community.makerdiary.com).
 
 ## Found a bug?
 
-If you found a bug in the source code, you can help us by submitting an issue to the [issue tracker](https://github.com/makerdiary/mx-keyboard/issues) in our GitHub repository. Even better, you can submit a Pull Request with a fix.
+If you find a bug in the source code, you can help us by submitting an issue to the [issue tracker](https://github.com/makerdiary/mx-keyboard/issues) in our GitHub repository. Even better, you can submit a Pull Request with a fix.
 
 ## Requesting a tutorial
 
-If you don't see what you're looking for, you can request a tutoial by submitting an issue to our GitHub Repository. We'd love to see your feedback!
+If you don't see what you're looking for, you can request a tutorial by submitting an issue to our GitHub Repository. We'd love to see your feedback!
 
-<a href="https://github.com/makerdiary/mx-keyboard/issues/new?title=Tutorial%20Request:%20%3Ctitle%3E&body=Description%0A%0ATechnical%20Level%0Abeginner%20%7C%20intermediate%20%7C%20advanced%0A%0ALength%0Ashort%20(%3C%20250%20words)%20%7C%20medium%20(250-500%20words)%20%7C%20long%20(1000%20words+)%0A"><button data-md-color-primary="red-bud" style="width: auto;"><i class="fa fa-github"></i> Request a tutoial</button></a>
+<a href="https://github.com/makerdiary/python-keyboard/issues/new?title=Tutorial%20Request:%20%3Ctitle%3E&body=Description%0A%0ATechnical%20Level%0Abeginner%20%7C%20intermediate%20%7C%20advanced%0A%0ALength%0Ashort%20(%3C%20250%20words)%20%7C%20medium%20(250-500%20words)%20%7C%20long%20(1000%20words+)%0A"><button data-md-color-primary="red-bud" style="width: auto;"><i class="fa fa-github"></i>Request a tutorial</button></a>
diff --git a/docs/assembling.md b/docs/assembling.md
@@ -4,16 +4,13 @@
 
 2. Attach the provided 2.4GHz and NFC cabled PCB antennas to the nRF52840 M.2 module as shown in the figure below:
 
-	![Attaching Antennas](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/attaching-antennas-to-m2.webp)
+   ![Attaching Antennas](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/attaching-antennas-to-m2.webp)
 
 3. Insert the module into the connector as shown in the figure below:
 
-	!!! Warning "Angle of Insertion"
-		Angled insertion is allowable and preferred to minimize the insertion force. The angle of insertion is **5° ~ 25°**, **typically 20°**.
-
-	![Module Insertion](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/m2-module-insertion.png)
+   **Warning regarding the angle of insertion: Angled insertion is allowable and is preferred to minimize the insertion force. The angle of insertion is 5° ~ 25°, typically 20°.**
+   ![Module Insertion](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/m2-module-insertion.png)
 
 4. Secure the module using the provided mounting screw as shown in the figure below:
 
-	![Secure the module](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/secure-m2-module-screw.png)
-
+   ![Secure the module](https://wiki.makerdiary.com/nrf52840-m2-devkit/assets/images/secure-m2-module-screw.png)
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,11 +1,11 @@
 # Keyboard Configuration
 
 M60 is not just a USB HID device, but also a USB storage device. Python code can be saved and executed in the keyboard. When the keyboard powers on, it will run the Python file `code.py` in its USB storage.
-In `code.py`, we can modify its keymap, add a macro and add a new feature to keyboard.
+Using `code.py`, you can modify they keyboard's keymap, and add macros, Tap-keys and more.
 
 ![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/CIRCUITPY-en.png)
 
-The default content of `code.py` is:
+An up-to-date `code.py` is included in this repository. Example content for `code.py` could be:
 
 ```python
 
@@ -95,13 +95,15 @@ keyboard.run()
 
 ```
 
-`keymap` contains multiple layers of keycodes. `macro_handler` is used to handle all macros. `pairs_handler` is used to handle any pair-keys.
+The `keymap` variable can contains multiple layers of keycodes. The `macro_handler` is used to handle all macros. The `pairs_handler` is used to handle any pair-keys.
 
-**When `code.py` is saved, the keyboard will reload it. If `code.py` has a syntax error, the keyboard will stop working. But, don't worry, it wouldn't damage the hardware. Fix the error and save it, then the keyboard will recover**
+**When `code.py` is saved, the keyboard will reload it. If `code.py` has a syntax error, the keyboard will stop working. But, don't worry, it will not damage the hardware. Just use another keyboard to fix the error and save the file, and then the keyboard will recover.**
 
-If you know how Python works, configuring the keyboard would be very easy. If not, we have some examples to get started.
+## Examples
 
-1.  To swap the positions of <kbd>Caps</kbd> and <kbd>LCtrl</kbd>, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`:
+If you already Python, configuring the keyboard is simple. If not, here are some examples to get started.
+
+1.  Swap the positions of <kbd>Caps</kbd> and <kbd>LCtrl</kbd>. To do this, just swap `CAPS` and `LCTRL` in `layer 0` of `keymap`:
 
     ```python
         # layer 0
@@ -114,7 +116,7 @@ If you know how Python works, configuring the keyboard would be very easy. If no
         ),
     ```
 
-2.  Instead of <kbd>D</kbd>, use <kbd>Caps</kbd> as a Tap-key to activate navigation functions. Only need to change `layer 0` to:
+2.  IUse <kbd>Caps</kbd> as a Tap-key to activate navigation functions, instead of <kbd>D</kbd>. To implement this, you only need to change `layer 0` to:
 
     ```python
         # layer 0
@@ -127,7 +129,7 @@ If you know how Python works, configuring the keyboard would be very easy. If no
         ),
     ```
 
-2.  Add a new macro. Use <kbd>Fn</kbd> and <kbd>Enter</kbd> to trigger No.1 macro. Just add `MACRO(1)` to `layer 1`:
+3.  Add a new macro. For example, the below uses <kbd>Fn</kbd> and <kbd>Enter</kbd> to trigger macro number 1 (the second macro, after macro number 0). Just add `MACRO(1)` to `layer 1`:
 
     ```python
         # layer 1
@@ -142,7 +144,7 @@ If you know how Python works, configuring the keyboard would be very easy. If no
 
     To define the function of the macro, please follow [the macro guide](macro.md)
 
-4.  Use <kbd>RShift</kbd>, <kbd>RGUI</kbd>, <kbd>Fn</kbd> and <kbd>RCtrl</kbd> as Tap-keys. Tapping them outputs arrows keys (press & release quickly). Just change `layer 0` to:
+4.  Use <kbd>RShift</kbd>, <kbd>RGUI</kbd>, <kbd>Fn</kbd> and <kbd>RCtrl</kbd> as Tap-keys, so that tapping them (_i.e._, quickly pressing & releasing them) outputs arrows keys. To do this, just change `layer 0` to:
 
     ```python
         # layer 0

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,63 +1,66 @@
 # Get started with M60 Keyboard
 
-M60 is a compact keyboard. It has a keymap composed of multiple layers, which is [similar to TMK Keyboard](https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/keymap.md). By default, No.0 layer is used:
+M60 is a compact keyboard. It has a keymap composed of multiple layers, [similar to TMK Keyboard](https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/keymap.md). By default, layer number 0 is used, which includes a normal key map:
 
 ![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/layer0.svg)
 
 ## Keymap
 
-As the 60% keyboard lacks a lot of keys such as F1~F12 and arrow keys, <kbd>Fn</kbd> is used to activate a new layer.
-When holding <kbd>Fn</kbd> down, the following keys are activated.
+As the 60% keyboard lacks a lot of keys such as F1~F12 and arrow keys, <kbd>Fn</kbd> is used to activate a second layer, layer number 1.
 
-![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/layer1.svg)
-
-+ <kbd>Fn</kbd> + <kbd>M</kbd> triggers No.0 macro
-+ <kbd>Fn</kbd> + <kbd>P</kbd> suspends the keyboard when only powered by battery.
-+ <kbd>Fn</kbd> + <kbd>B</kbd> enters its bootloader (only for upgrade)
+By default, holding <kbd>Fn</kbd> down activates the following functions:
 
-Except <kbd>Fn</kbd>, a normal key can be used as a Tap-key,  which is holding a key down to activate an alternate function.
+![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/layer1.svg)
 
-### Using <kbd>B</kbd> to configure Bluetooth and USB
+- <kbd>Fn</kbd> + <kbd>M</kbd> triggers No.0 macro
+- <kbd>Fn</kbd> + <kbd>P</kbd> suspends the keyboard when only powered by battery.
+- <kbd>Fn</kbd> + <kbd>B</kbd> enters its bootloader (only for used for firmware upgrades)
 
-<kbd>B</kbd> is used as a Tap-key to configure Bluetooth and USB. Taping <kbd>B</kbd> outputs `b` (press & release quickly). Holding <kbd>B</kbd> down activates another new layer. With the layer, the following functions are available:
+Except for <kbd>Fn</kbd>, any normal key can be used as a Tap-key. A Tap-key is a key that can be used as an ordinary key when tapped, or can be held down to activate alternate functions.
 
-+ <kbd>B</kbd> + <kbd>Esc</kbd> toggles Bluetooth
-+ <kbd>B</kbd> + <kbd>0</kbd> ~ <kbd>9</kbd> changes Bluetooth ID to switch between multiple computers and phones
-+ <kbd>B</kbd> + <kbd>U</kbd> toggles USB
+All of the default Tap-keys, including <kbd>D</kbd>, <kbd>B</kbd>, and <kbd>;</kbd> can be [re-configured](configuration.md).
 
 ### Using <kbd>D</kbd> for Navigation
 
-<kbd>D</kbd> is also used as a Tap key for navigation functions.
+<kbd>D</kbd> is the default Tap-key to activate the navigation functions. Holding it activates layer number 2, which includes navigation keys:
 
 ![](https://gitee.com/makerdiary/python-keyboard/raw/master/img/d-for-navigation.png)
 
-+ <kbd>D</kbd> + <kbd>H</kbd> → <kbd>←</kbd>
-+ <kbd>D</kbd> + <kbd>J</kbd> → <kbd>↓</kbd>
-+ <kbd>D</kbd> + <kbd>K</kbd> → <kbd>↑</kbd>
-+ <kbd>D</kbd> + <kbd>L</kbd> → <kbd>→</kbd>
-+ <kbd>D</kbd> + <kbd>U</kbd> → <kbd>PgUp</kbd>
-+ <kbd>D</kbd> + <kbd>N</kbd> → <kbd>PgDn</kbd>
+- <kbd>D</kbd> + <kbd>H</kbd> → <kbd>←</kbd>
+- <kbd>D</kbd> + <kbd>J</kbd> → <kbd>↓</kbd>
+- <kbd>D</kbd> + <kbd>K</kbd> → <kbd>↑</kbd>
+- <kbd>D</kbd> + <kbd>L</kbd> → <kbd>→</kbd>
+- <kbd>D</kbd> + <kbd>U</kbd> → <kbd>PgUp</kbd>
+- <kbd>D</kbd> + <kbd>N</kbd> → <kbd>PgDn</kbd>
+
+### Using <kbd>B</kbd> to Configure Bluetooth and USB
+
+<kbd>B</kbd> is the default Tap-key to configure Bluetooth and USB. Tapping <kbd>B</kbd> (_i.e._, pressing & releasing it quickly) outputs `b`. Holding <kbd>B</kbd> down activates another the Bluetooth keyboard layer, layer number 3. When the Bluetooth layer is active, the following functions are available:
+
+- <kbd>B</kbd> + <kbd>Esc</kbd> toggles Bluetooth
+- <kbd>B</kbd> + <kbd>0</kbd> ~ <kbd>9</kbd> changes Bluetooth ID to switch between multiple computers and phones
+- <kbd>B</kbd> + <kbd>U</kbd> toggles USB
 
 ### Using <kbd>;</kbd> as <kbd>Ctrl</kbd>
 
-<kbd>;</kbd> is another type of Tap-key. Taping <kbd>;</kbd> outputs `;`. However, holding <kbd>;</kbd> down outputs `Ctrl` instead of activating a layer.
+<kbd>;</kbd> is a different type of Tap-key. Tapping <kbd>;</kbd> outputs `;`. However, holding <kbd>;</kbd> down outputs `Ctrl` instead of activating a layer.
 
 ![](https://github.com/xiongyihui/keyboard/raw/master/img/semicolon_as_ctrl.png)
 
-+ <kbd>;</kbd> + <kbd>c</kbd> = <kbd>Ctrl</kbd> + <kbd>c</kbd>
-+ <kbd>;</kbd> + <kbd>v</kbd> = <kbd>Ctrl</kbd> + <kbd>v</kbd>
-+ <kbd>;</kbd> + <kbd>x</kbd> = <kbd>Ctrl</kbd> + <kbd>x</kbd>
-+ <kbd>;</kbd> + <kbd>a</kbd> = <kbd>Ctrl</kbd> + <kbd>a</kbd>
-
+- <kbd>;</kbd> + <kbd>c</kbd> = <kbd>Ctrl</kbd> + <kbd>c</kbd>
+- <kbd>;</kbd> + <kbd>v</kbd> = <kbd>Ctrl</kbd> + <kbd>v</kbd>
+- <kbd>;</kbd> + <kbd>x</kbd> = <kbd>Ctrl</kbd> + <kbd>x</kbd>
+- <kbd>;</kbd> + <kbd>a</kbd> = <kbd>Ctrl</kbd> + <kbd>a</kbd>
 
 ## Using Pair-keys
 
-Simultaneously pressing two keys (interval less than 10ms) activates an alternate function.
-By default, <kbd>J</kbd> <kbd>K</kbd> are used as a pair-keys. When simultaneously pressing <kbd>J</kbd> and <kbd>K</kbd> in a text editor, it will output a pre-defined string.
+Simultaneously pressing two keys (_i.e._, pressing them in an interval of less than 10ms) activates an alternate function.
 
-## Setup Bluetooth
+Two sets of pair-keys are configured by default, to illustrate how to setup these keys. These include <kbd>J</kbd> <kbd>K</kbd> and <kbd>U</kbd> <kbd>I</kbd>. As shipped, simultaneously pressing <kbd>J</kbd> and <kbd>K</kbd> or <kbd>U</kbd> and <kbd>I</kbd> in a text editor will output a pre-defined string (_e.g._, "You just triggered pair keys #0").
 
-First, we press <kbd>B</kbd> + <kbd>1</kbd> to start Bluetooth advertising, and then we will see the blue LED under <kbd>1</kbd> is in breathing mode：
+## How to Setup Bluetooth
+
+First, press <kbd>B</kbd> + <kbd>1</kbd> to start Bluetooth advertising. You will then see the blue LED under <kbd>1</kbd> enter in "breathing" mode and flash slowly：
 
 ![](https://gitee.com/makerdiary/python-keyboard/raw/resource/img/ble_broadcast.gif)
 
@@ -73,8 +76,10 @@ Choose `Bluetooth` in the `Add a device` dialog, then you will see the device `P
 
 <img src="https://gitee.com/makerdiary/python-keyboard/raw/resource/img/windows-add-bluetooth-device-en.png" width="400">
 
-When to connect the keyboard to a second computer, just use <kbd>B</kbd> + <kbd>2</kbd> to start connecting. From <kbd>0</kbd> to <kbd>9</kbd>, the keyboard can connect to 10 bluetooth devices.
+In order to connect the keyboard to a second computer, just use <kbd>B</kbd> + <kbd>2</kbd> to start connecting. From <kbd>0</kbd> to <kbd>9</kbd>, the keyboard can connect to 10 bluetooth devices.
+
+## Go Further
 
-## Go further
+We hope M60 keyboard incites ideas to make a keyboard more productive, all without having to install any third-party software or drivers on your computer.
 
-We hope M60 brings you an idea to make a keyboard more productive. You may have your own thoughts of configuring a keyboard. Follow [the configuring guide](configuration.md) to find what works best for you.
+If you have your own thoughts on how to best configure the keyboard, just follow [the configuration guide](configuration.md) to find what works best for you.
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 # M60 Mechanical Keyboard
 
- **En** | [中文][1]
+**En** | [中文][1]
 
 M60 is a hot-swappable 60% Keyboard with USB, BLE 5.0 and RGB backlight. It is highly configurable and extensible.
 It can run Python code saved in its USB storage, which makes it super powerful. It has very low power consumption and only needs about 160uA current when connected to a computer via Bluetooth. It is one of the lowest latency USB keyboards.
@@ -9,32 +9,35 @@ It can run Python code saved in its USB storage, which makes it super powerful.
 
 ## Features
 
-- BLE 5.0 Multi-pairing up to 10 devices
-- Hot-swappable
-- USB Type-C
+- Bluetooth, including BLE 5.0 multi-pairing up to 10 devices
+- Hot-swappable key switch mounts
+- USB Type-C connector
 - Standard 60% layout (61 keys)
 - 6KRO
-- RGB backlit
+- RGB backlight (pending software support)
 - Supports Windows/macOS/Linux/iOS/Android
 - Low power consumption
 - All keys remappable
 - Up to 32 layers
 - Macros
 - Pair-keys
+- Tap-keys
 
 ## Specs
 
-|                 | M60 Keyboard                                                                      |
-|-----------------|-----------------------------------------------------------------------------------|
-| Core Module     | nRF52840, Arm Cortex-M4F, 64MHz, 256KB RAM, 1MB FLASH, 8MB QSPI Flash, M.2 KEY-E  |
-| Wireless        | Bluetooth Low Energy 5.0, NFC                                                     |
-| USB             | Type-C                                                                            |
-| Layout          | 60% (61 Keys)                                                                     |
-| Hot-Swappable   | Yes                                                                               |
-| Switch Option   | Cherry MX compatible Switches                                                     |
-| Backlight       | 64 RGB LEDs, IS32FL3733                                                           |
-|Battery Connector| JST 1.25mm 3-Pin                                                                  |
-| RF Antennas     | 2.4GHz Cabled PCB Antenna, NFC Cabled PCB Antenna                                 |
-| Dimensions      | 285 mm x 94.6 mm                                                                  |
+|                   | M60 Keyboard                                                                     |
+| ----------------- | -------------------------------------------------------------------------------- |
+| Core Module       | nRF52840, Arm Cortex-M4F, 64MHz, 256KB RAM, 1MB FLASH, 8MB QSPI Flash, M.2 KEY-E |
+| Wireless          | Bluetooth Low Energy 5.0, NFC                                                    |
+| USB               | Type-C                                                                           |
+| Layout            | 60% (61 Keys)                                                                    |
+| Hot-Swappable     | Yes                                                                              |
+| Switch Option     | Cherry MX compatible Switches                                                    |
+| Backlight         | 64 RGB LEDs, IS32FL3733                                                          |
+| Battery Connector | JST 1.25mm 3-Pin                                                                 |
+| RF Antennas       | 2.4GHz Cabled PCB Antenna, NFC Cabled PCB Antenna                                |
+| Dimensions        | 285 mm x 94.6 mm (compatible with DZ60 cases)                                    |
+
+**Note: The M60 PCB uses a north-facing switch orientation. If you plan to use Cherry MX or low-profile keycaps, be sure to purchase key switches that are beveled on both the north and south ends. See Issue #3.**
 
 [1]: https://gitee.com/makerdiary/python-keyboard/wikis/pages