diff --git a/packages/flutter/lib/src/services/raw_keyboard.dart b/packages/flutter/lib/src/services/raw_keyboard.dart
index e7789eb17fe1..35985390510e 100644
--- a/packages/flutter/lib/src/services/raw_keyboard.dart
+++ b/packages/flutter/lib/src/services/raw_keyboard.dart
@@ -585,6 +585,24 @@ typedef RawKeyEventHandler = bool Function(RawKeyEvent event);
 /// These key events are typically only key events generated by a hardware
 /// keyboard, and not those from software keyboards or input method editors.
 ///
+/// ## Compared to [HardwareKeyboard]
+///
+/// [RawKeyboard] is the legacy API, and will be deprecated and removed in the
+/// future. It is recommended to always use [HardwareKeyboard] and [KeyEvent]
+/// APIs (such as [FocusNode.onKeyEvent]) to handle key events.
+///
+/// Behavior-wise, [RawKeyboard] provides a less unified, less regular
+/// event model than [HardwareKeyboard]. For example:
+///
+///  * Down events might not be matched with an up event, and vice versa (the
+///    set of pressed keys is silently updated).
+///  * The logical key of the down event might not be the same as that of the up
+///    event.
+///  * Down events and repeat events are not easily distinguishable (must be
+///    tracked manually).
+///  * Lock modes (such as CapsLock) only have their "enabled" state recorded.
+///    There's no way to acquire their pressing state.
+///
 /// See also:
 ///
 ///  * [RawKeyDownEvent] and [RawKeyUpEvent], the classes used to describe
@@ -592,6 +610,7 @@ typedef RawKeyEventHandler = bool Function(RawKeyEvent event);
 ///  * [RawKeyboardListener], a widget that listens for raw key events.
 ///  * [SystemChannels.keyEvent], the low-level channel used for receiving
 ///    events from the system.
+///  * [HardwareKeyboard], the recommended replacement.
 class RawKeyboard {
   RawKeyboard._();