fix(docs): work on the documentation comprehension

docs/docs/feature/keymaps.md

@@ -4,10 +4,9 @@ title: Keymaps & Behaviors
 sidebar_label: Keymaps
 ---
 
-ZMK uses a declarative approach to keymaps, instead of using C code for all keymap configuration.
+ZMK uses a declarative approach to keymaps, instead of using C code for all keymap configuration. Right now,
-Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for
+ZMK uses the devicetree syntax to declare those keymaps. In the future, we hope to support loading keymaps
-supporting dynamic loading of declarative keymaps, e.g., over USB Mass Storage or via a custom BLE
+dynamically over USB Mass Storage, or a custom BLE service.
-service.
 
 :::note
 For advanced users looking to implement custom behaviors for their keymaps, this will be possible
@@ -23,13 +22,12 @@ their user config directory, and customize the keymap to their liking.
 
 ## Behaviors
 
-ZMK implements the concept of "behaviors", which can be bound to a specific key position, sensor (encoder),
+ZMK implements the concept of "behaviors". Each can be bound to a specific key position, sensor (encoder), or
-or layer, to perform particular actions when events occur for that binding (e.g. when a specific key position
+layer. The "behavior" will perform particular actions when events occur for that binding.
-is pressed or released, or an encoder triggers a rotation event).
 
-For example, the simplest behavior in ZMK is the "key press" behavior, which responds to a key position
+For example, the simplest behavior in ZMK is the "key press" behavior. It responds to one key on the keyboard.
-(a certain spot on the keyboard), and when that position is pressed, send a keycode to the host, and
+When pressed, it will send a keycode to the [host](/docs/terms#host), and when the key is
-when the key position is released, updates the host notifying of the keycode being released.
+released, it updates the host notifying the release of the keycode.
 
 For the full set of possible behaviors, start at the [Key Press](/docs/behavior/key-press) behavior.
 
@@ -46,11 +44,11 @@ in ZMK contains a set of bindings that bind a certain behavior to a certain key
 In addition to the base default layer (which can be changed), certain bound behaviors may also
 enable/disable additional layers "on top" of the default layer.
 
-When a key location is pressed/released, the stack of all active layers from "top to bottom" is used,
+When a key location is pressed or released, the stack of all active [layers](/docs/terms#layer) from "top to
-and the event is sent to the behavior bound at that position in each layer, for it to perform whatever
+bottom" is used. The event is sent to the [behavior](/docs/terms#behavior) bound at that position in each
-actions it wants to in reaction to the event. Those behaviors can choose to "handle" the event, and stop
+layer. Those [behaviors](/docs/terms#behavior) can "handle" the event, stop it from being passed to any lower
-it from being passed to any lower layers, or may choose to "pass it along", and let the next layer
+[layers](/docs/terms#layer), or choose to "pass it along" and let the [layer](/docs/terms#layer) below handle
-in the stack _also_ get the event.
+the event.
 
 ## Behavior Bindings
 
@@ -65,7 +63,7 @@ be used for that key position.
 
 In this case, the `A` is actually a define for the raw HID keycode, to make keymaps easier to read and write.
 
-For example of a binding that uses two parameters, you can see how "mod-tap" (`mt`) is bound:
+For an example of a binding that uses two parameters, you can see how "mod-tap" (`mt`) is bound:
 
 ```
 &mt MOD_LSFT D
@@ -80,8 +78,9 @@ A keymap file is composed of several sections, that together make up a valid dev
 
 ### Includes
 
-The devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders
+The devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows
-for what would otherwise be cryptic integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files.
+using standard C defines to create meaningful placeholders for what would otherwise be cryptic
+integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files.
 
 The top two lines of most keymaps should include:
 
@@ -146,7 +145,7 @@ that defines just one layer for this keymap:
 
 Each layer should have:
 
-1. A `bindings` property that will be a list of behaviour bindings, one for each key position for the keyboard.
+1. A `bindings` property that will be a list of behavior bindings, one for each key position for the keyboard.
 1. (Optional) A `sensor-bindings` property that will be a list of behavior bindings for each sensor on the keyboard. (Currently, only encoders are supported as sensor hardware, but in the future devices like trackpoints would be supported the same way)
 
 For the full set of possible behaviors, start at the [Key Press](/docs/behavior/key-press) behavior.

docs/docs/terms.md

@@ -0,0 +1,34 @@
+---
+id: terms
+title: Glossary of Terms
+sidebar_label: Terms
+---
+
+### Host
+
+The device that will receive the key strokes from the keyboard
+
+### Central
+
+The part of the keyboard that communicates with the host
+
+### Peripheral
+
+The other wireless parts of the keyboard. (e.g., other half of a split keyboard)
+
+### BLE
+
+Bluetooth Low Energy
+
+### Behavior
+
+The action a key may use.
+
+### Event
+
+Needs definition
+
+### Layer
+
+A compilation of [behaviors](#behavior) for each key on the keyboard. There may be more than one layer for a
+keyboard.

docs/sidebars.js

@@ -1,6 +1,6 @@
 module.exports = {
   someSidebar: {
-    "Getting Started": ["intro", "hardware", "faq", "user-setup"],
+    "Getting Started": ["intro", "hardware", "faq", "terms", "user-setup"],
     Features: [
       "feature/keymaps",
       "feature/displays",