1 files changed, 74 insertions, 13 deletions
diff --git a/docs/tap_hold.md b/docs/tap_hold.md
index a0b648694b..2dc57f03c2 100644
--- a/docs/tap_hold.md
+++ b/docs/tap_hold.md
@@ -4,6 +4,38 @@ While Tap-Hold options are fantastic, they are not without their issues.  We hav
 
 These options let you modify the behavior of the Tap-Hold keys.
 
+## Tapping Term
+
+The crux of all of the following features is the tapping term setting.  This determines what is a tap and what is a hold.  And the exact timing for this to feel natural can vary from keyboard to keyboard, from switch to switch, and from key to key.  
+
+You can set the global time for this by adding the following setting to your `config.h`: 
+
+```c
+#define TAPPING_TERM 200
+```
+
+This setting is defined in milliseconds, and does default to 200ms.  This is a good average for a majority of people. 
+
+For more granular control of this feature, you can add the following to your `config.h`: 
+```c
+#define TAPPING_TERM_PER_KEY
+```
+
+You can then add the following function to your keymap:
+
+```c
+uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case SFT_T(KC_SPC):
+            return TAPPING_TERM + 1250;
+        case LT(1, KC_GRV):
+            return 130;
+        default:
+            return TAPPING_TERM;
+}
+```
+
+
 ## Permissive Hold
 
 As of [PR#1359](https://github.com/qmk/qmk_firmware/pull/1359/), there is a new `config.h` option:
@@ -27,6 +59,25 @@ Normally, if you do all this within the `TAPPING_TERM` (default: 200ms) this wil
 
 ?> If you have `Ignore Mod Tap Interrupt` enabled, as well, this will modify how both work. The regular key has the modifier added if the first key is released first or if both keys are held longer than the `TAPPING_TERM`.
 
+For more granular control of this feature, you can add the following to your `config.h`:
+
+```c
+#define PERMISSIVE_HOLD_PER_KEY
+```
+
+You can then add the following function to your keymap:
+
+```c
+bool get_permissive_hold(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case LT(1, KC_BSPC):
+            return true;
+        default:
+            return false;
+    }
+}
+```
+
 ## Ignore Mod Tap Interrupt
 
 To enable this setting, add this to your `config.h`:
@@ -62,13 +113,13 @@ For more granular control of this feature, you can add the following to your `co
 You can then add the following function to your keymap:
 
 ```c
-bool get_ignore_mod_tap_interrupt(uint16_t keycode) {
-  switch (keycode) {
-    case SFT_T(KC_SPC):
-      return true;
-    default:
-      return false;
-  }
+bool get_ignore_mod_tap_interrupt(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case SFT_T(KC_SPC):
+            return true;
+        default:
+            return false;
+    }
 }
 ```
 
@@ -106,12 +157,12 @@ You can then add the following function to your keymap:
 
 ```c
 bool get_tapping_force_hold(uint16_t keycode, keyrecord_t *record) {
-  switch (keycode) {
-    case LT(1, KC_BSPC):
-      return true;
-    default:
-      return false;
-  }
+    switch (keycode) {
+        case LT(1, KC_BSPC):
+            return true;
+        default:
+            return false;
+    }
 }
 ```
 
@@ -126,3 +177,13 @@ To enable `retro tapping`, add the following to your `config.h`:
 Holding and releasing a dual function key without pressing another key will result in nothing happening. With retro tapping enabled, releasing the key without pressing another will send the original keycode even if it is outside the tapping term.
 
 For instance, holding and releasing `LT(2, KC_SPACE)` without hitting another key will result in nothing happening. With this enabled, it will send `KC_SPACE` instead.
+
+## Why do we include the key record for the per key functions? 
+
+One thing that you may notice is that we include the key record for all of the "per key" functions, and may be wondering why we do that. 
+
+Well, it's simply really: customization.  But specifically, it depends on how your keyboard is wired up.  For instance, if each row is actually using a row in the keyboard's matrix, then it may be simpler to use `if (record->event.row == 3)` instead of checking a whole bunch of keycodes.  Which is especially good for those people using the Tap Hold type keys on the home row. So you could fine tune those to not interfere with your normal typing. 
+
+## Why is there no `*_kb` or `*_user` functions?!
+
+Unlike many of the other functions here, there isn't a need (or even reason) to have a quantum or keyboard level function. Only user level functions are useful here, so no need to mark them as such.