diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index 27adb6a892f..f5f260fe4ab 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -280,10 +280,13 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       same `partition`. If there is no `persist:` prefix, the page will use an
       in-memory session. By assigning the same `partition`, multiple pages can share
       the same session. Default is the default session.
-    * `affinity` String (optional) - Sets the expected process hosting the page. Allow to gather
-      several pages in the same process. There are known limitations:
-      you can not host in the same site, pages with different preload file,
-      nodeIntegration or sandbox preferences.
+    * `affinity` String (optional) - When specified, web pages with the same
+      `affinity` will run in the same renderer process. Note that due to reusing
+      the renderer process, certain `webPreferences` options will also be shared
+      between the web pages even when you specified different values for them,
+      including but not limited to `preload`, `sandbox` and `nodeIntegration`.
+      So it is suggested to use exact same `webPreferences` for web pages with
+      the same `affinity`.
     * `zoomFactor` Number (optional) - The default zoom factor of the page, `3.0` represents
       `300%`. Default is `1.0`.
     * `javascript` Boolean (optional) - Enables JavaScript support. Default is `true`.