Add tap-hold docs, update mod-tap docs

docs/docs/behavior/hold-tap.md

@@ -0,0 +1,62 @@
+---
+title: Hold-tap behavior
+sidebar_label: Hold-Tap
+---
+
+## Summary
+Hold-tap is the basis for other behaviors such as layer-tap and mod-tap. 
+
+Simply put, the hold-tap key will output the 'hold' behavior if it's held for a while, and output the 'tap' behavior when it's tapped quickly.
+
+
+### Hold-Tap
+The `tapping_term_ms` parameter decides between a 'tap' and a 'hold'.
+
+![Simple behavior](../assets/hold-tap/case1_2.png)
+
+By default, the hold-tap is configured to also select the 'hold' functionality if another key is tapped while it's active: 
+
+![Hold preferred behavior](../assets/hold-tap/case1_2.png)
+
+We call this the 'hold-preferred' flavor of hold-taps. While this flavor may work very well for a ctrl/escape key, it's not very well suited for home-row mods or layer-taps. That's why there are two more flavors to choose from: 'tap-preferred' and 'balanced'.
+
+![Hold-tap comparison](../assets/hold-tap/comparison.png)
+
+### Configuration
+A code example which configures a mod-tap setting that works with homerow mods:
+
+```
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/keys.h>
+
+/ {
+	behaviors {
+		&hm: homerow_mods {
+			compatible = "zmk,behavior-hold-tap";
+			label = "homerow_mods";
+			#binding-cells = <2>;
+			tapping_term_ms = <175>;
+			flavor = "balanced";
+			bindings = <&kp>, <&kp>;
+		};
+	};
+		
+	keymap {
+		compatible = "zmk,keymap";
+
+		default_layer {
+			bindings = <
+	            &hm LCTL A &hm LGUI S &hm LALT D &hm LSFT F
+			>;
+		};
+	};
+};
+
+```
+
+If this config does not work for you, try the flavor "tap-preferred" and a short tapping_term_ms such as 120ms.
+
+If you want to use a tap-hold with a keycode from a different code page, you have to define another behavior with another "bindings" parameter.For example, if you want to use SHIFT and volume up, define the bindings like `bindings = <&kp>, <&cp>;`. Only single-argument behaviors are supported at the moment.
+
+#### Note
+Astute readers may notice similarities between the possible behaviors in ZMK and other firmware, such as QMK. The hold-preferred flavor works similar to the `HOLD_ON_OTHER_KEY_PRESS` setting. The 'balanced' flavor is similar to the `PERMISSIVE_HOLD` setting, and the `tap-preferred` flavor is similar to `IGNORE_MOD_TAP_INTERRUPT`.

docs/docs/behavior/mod-tap.md

@@ -5,13 +5,9 @@ sidebar_label: Mod-Tap
 
 ## Summary
 
-The Mod-Tap behavior allows varying the effect of pressing and releasing a key position depending
-on whether it is used with other simultaneous key presses at the same time.
+The Mod-Tap sends a different keypress, if it's tapped or held. When you tap the key shortly, the first keycode is sent. If you hold the key for longer than 200ms, the second keycode is sent.
 
-If pressed and released independently, the Mod-Tap behavior will send the press and release events
-for the configure keycode. If pressed and held while another key is pressed and released, then
-the configured modifiers will be applied to that _other_ key press, and no press will be generated
-on the release of the Mod-Tap key.
+If you press another key within the 200ms, the 'mod' behavior is also activated.
 
 ## Mod-Tap
 
@@ -20,11 +16,28 @@ The Mod-Tap behavior either acts as a held modifier, or as a tapped keycode.
 ### Behavior Binding
 
 - Reference: `&mt`
-- Parameter #1: The modifiers to be used when activating as a modifier, e.g. `MOD_LSFT`
+- Parameter #1: The keycode to be sent when activating as a modifier, e.g. `LSFT`
 - Parameter #2: The keycode to sent when used as a tap, e.g. `A`, `B`.
 
 Example:
 
 ```
 &mt MOD_LSFT A
 ```
+
+### Configuration
+
+You can configure a different tapping term in your keymap:
+
+```
+&mt {
+    tapping_term_ms: <400>;
+} 
+
+/ {
+    keymap {
+        ...
+    }
+}
+```
+