Diff
1diff --git a/plugins/vi-mode/README.md b/plugins/vi-mode/README.md
2index b59d5f279618110004533cbdf4344975d7553d3b..46bb6d07008ac69be8dd47d306b410c25dc13f2c 100644
3--- a/plugins/vi-mode/README.md
4+++ b/plugins/vi-mode/README.md
5@@ -64,7 +64,7 @@ NOTE: some of these key bindings are set by zsh by default when using a vi-mode
6
7 - `vv` : Edit current command line in Vim
8
9-NOTE: this used to be bound to `v`. That is now the default (`visual-mode`)
10+NOTE: this used to be bound to `v`. That is now the default (`visual-mode`).
11
12 ### Movement
13
14@@ -107,3 +107,21 @@ NOTE: this used to be bound to `v`. That is now the default (`visual-mode`)
15 - `R` : Enter replace mode: Each character replaces existing one
16 - `x` : Delete `count` characters under and after the cursor
17 - `X` : Delete `count` characters before the cursor
18+
19+## Known issues
20+
21+### Low `$KEYTIMEOUT`
22+
23+A low `$KEYTIMEOUT` value (< 15) means that key bindings that need multiple characters,
24+like `vv`, will be very difficult to trigger. `$KEYTIMEOUT` controls the number of
25+milliseconds that must pass before a key press is read and the appropriate key binding
26+is triggered. For multi-character key bindings, the key presses need to happen before
27+the timeout is reached, so on low timeouts the key press happens too slow, and therefore
28+another key binding is triggered.
29+
30+We recommend either setting `$KEYTIMEOUT` to a higher value, or remapping the key bindings
31+that you want to trigger to a keyboard sequence. For example:
32+
33+```zsh
34+bindkey -M vicmd 'V' edit-command-line # this remaps `vv` to `V` (but overrides `visual-mode`)
35+```