diff --git a/src/v2/guide/events.md b/src/v2/guide/events.md
index 8f14384f30..cfdfcbf7ed 100644
--- a/src/v2/guide/events.md
+++ b/src/v2/guide/events.md
@@ -223,24 +223,28 @@ The `.passive` modifier is especially useful for improving performance on mobile
 
 ## Key Modifiers
 
-When listening for keyboard events, we often need to check for common key codes. Vue also allows adding key modifiers for `v-on` when listening for key events:
+When listening for keyboard events, we often need to check for specific keys. Vue allows adding key modifiers for `v-on` when listening for key events:
 
 ``` html
-<!-- only call `vm.submit()` when the `keyCode` is 13 -->
-<input v-on:keyup.13="submit">
+<!-- only call `vm.submit()` when the `key` is PageDown -->
+<input @keyup.page-down="onPageDown">
 ```
 
-Remembering all the `keyCode`s is a hassle, so Vue provides aliases for the most commonly used keys:
+In the above example, the handler will only be called if `$event.key` is equal to `'PageDown'`.
 
-``` html
-<!-- same as above -->
-<input v-on:keyup.enter="submit">
+You can directly use any valid key names exposed via [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) as modifiers by converting them to kebab-case.
+
+### Key Codes
+
+<p class="tip">The use of `keyCode` events [is deprecated](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode) and may not be supported in new browsers.</p>
 
-<!-- also works for shorthand -->
-<input @keyup.enter="submit">
+Using `keyCode` attributes is also permitted:
+
+``` html
+<input v-on:keyup.13="submit">
 ```
 
-Here's the full list of key modifier aliases:
+Vue provides aliases for the most commonly used key codes when necessary for legacy browser support:
 
 - `.enter`
 - `.tab`
@@ -252,6 +256,8 @@ Here's the full list of key modifier aliases:
 - `.left`
 - `.right`
 
+<p class="tip">A few keys (`.esc` and all arrow keys) have inconsistent `key` values in IE9, so these built-in aliases should be preferred if you need to support IE9.</p>
+
 You can also [define custom key modifier aliases](../api/#keyCodes) via the global `config.keyCodes` object:
 
 ``` js
@@ -259,20 +265,6 @@ You can also [define custom key modifier aliases](../api/#keyCodes) via the glob
 Vue.config.keyCodes.f1 = 112
 ```
 
-### Automatic Key Modifiers
-
-> New in 2.5.0+
-
-You can also directly use any valid key names exposed via [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) as modifiers by converting them to kebab-case:
-
-``` html
-<input @keyup.page-down="onPageDown">
-```
-
-In the above example, the handler will only be called if `$event.key === 'PageDown'`.
-
-<p class="tip">A few keys (`.esc` and all arrow keys) have inconsistent `key` values in IE9, their built-in aliases should be preferred if you need to support IE9.</p>
-
 ## System Modifier Keys
 
 > New in 2.1.0+