diff --git a/docs/api/app.md b/docs/api/app.md
index 38a6f0fd14..f76559d3db 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -250,7 +250,9 @@ Returns:
 
 Emitted when the user clicks the native macOS new tab button. The new
 tab button is only visible if the current `BrowserWindow` has a
-`tabbingIdentifier`
+`tabbingIdentifier`.
+
+You must create a window in this handler in order for macOS tabbing to work as expected.
 
 ### Event: 'browser-window-blur'
 
diff --git a/docs/api/base-window.md b/docs/api/base-window.md
index 30d80fc7c1..4ab9afb72b 100644
--- a/docs/api/base-window.md
+++ b/docs/api/base-window.md
@@ -351,7 +351,11 @@ Emitted when the window has closed a sheet.
 
 #### Event: 'new-window-for-tab' _macOS_
 
-Emitted when the native new tab button is clicked.
+Emitted when the user clicks the native macOS new tab button. The new
+tab button is only visible if the current `BrowserWindow` has a
+`tabbingIdentifier`.
+
+You must create a window in this handler in order for macOS tabbing to work as expected.
 
 #### Event: 'system-context-menu' _Windows_ _Linux_
 
diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index 6f05246da4..8e46060d6b 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -431,7 +431,11 @@ Emitted when the window has closed a sheet.
 
 #### Event: 'new-window-for-tab' _macOS_
 
-Emitted when the native new tab button is clicked.
+Emitted when the user clicks the native macOS new tab button. The new
+tab button is only visible if the current `BrowserWindow` has a
+`tabbingIdentifier`.
+
+You must create a window in this handler in order for macOS tabbing to work as expected.
 
 #### Event: 'system-context-menu' _Windows_ _Linux_