diff --git a/doc/api/tty.md b/doc/api/tty.md
index 8f250e45d6..963de892cb 100644
--- a/doc/api/tty.md
+++ b/doc/api/tty.md
@@ -88,6 +88,15 @@ process.stdout.on('resize', () => {
 });
 ```
 
+*Note*: On Windows resize events will be emitted only if stdin is unpaused
+(by a call to `resume()` or by adding a data listener) and in raw mode. It can
+also be triggered if a terminal control sequence that moves the cursor is
+written to the screen. Also, the resize event will only be signaled if the
+console screen buffer height was also changed. For example shrinking the
+console window height will not cause the resize event to be emitted. Increasing
+the console window height will only be registered when the new console window
+height is greater than the current console buffer size.
+
 ### writeStream.columns
 <!-- YAML
 added: v0.7.7