diff --git a/docs/api/app.md b/docs/api/app.md
index 40bca9c2d469..de1ae1138f9a 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -60,6 +60,10 @@ Emitted before the application starts closing its windows.
 Calling `event.preventDefault()` will prevent the default behaviour, which is
 terminating the application.
 
+**Note:** If application quit was initiated by `autoUpdater.quitAndInstall()`
+then `before-quit` is emitted *after* emitting `close` event on all windows and
+closing them.
+
 ### Event: 'will-quit'
 
 Returns:
diff --git a/docs/api/auto-updater.md b/docs/api/auto-updater.md
index 53d6b1373620..720e2896915f 100644
--- a/docs/api/auto-updater.md
+++ b/docs/api/auto-updater.md
@@ -121,6 +121,10 @@ using this API.
 Restarts the app and installs the update after it has been downloaded. It
 should only be called after `update-downloaded` has been emitted.
 
+**Note:** `autoUpdater.quitAndInstall()` will close all application windows
+first and only emit `before-quit` event on `app` after that. This is different
+from the normal quit event sequence.
+
 [squirrel-mac]: https://github.com/Squirrel/Squirrel.Mac
 [server-support]: https://github.com/Squirrel/Squirrel.Mac#server-support
 [squirrel-windows]: https://github.com/Squirrel/Squirrel.Windows