From b33c04d0412c6b5341ba04d28f8eca71ce487e09 Mon Sep 17 00:00:00 2001
From: Cheng Zhao <zcbenz@gmail.com>
Date: Fri, 20 May 2016 19:58:47 +0900
Subject: [PATCH] docs: Recommend to use ICO icon

---
 docs/api/browser-window.md | 5 +++--
 docs/api/native-image.md   | 7 ++++++-
 docs/api/tray.md           | 1 +
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index 93785878d146..900212c8fe6e 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -65,8 +65,9 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     `false`.
   * `kiosk` Boolean - The kiosk mode. Default is `false`.
   * `title` String - Default window title. Default is `"Electron"`.
-  * `icon` [NativeImage](native-image.md) - The window icon, when omitted on
-    Windows the executable's icon would be used as window icon.
+  * `icon` [NativeImage](native-image.md) - The window icon. On Windows it is
+    recommended to use `ICO` icons to get best visual effects, you can also
+    leave it undefined so the executable's icon will be used.
   * `show` Boolean - Whether window should be shown when created. Default is
     `true`.
   * `frame` Boolean - Specify `false` to create a
diff --git a/docs/api/native-image.md b/docs/api/native-image.md
index b8479ac3b386..9790daaca49e 100644
--- a/docs/api/native-image.md
+++ b/docs/api/native-image.md
@@ -25,7 +25,12 @@ const appIcon = new Tray(image);
 Currently `PNG` and `JPEG` image formats are supported. `PNG` is recommended
 because of its support for transparency and lossless compression.
 
-On Windows, you can also load an `ICO` icon from a file path.
+On Windows, you can also load `ICO` icons from file paths, to get best visual
+effects it is recommended to include at least followings sizes in the icon:
+
+* 16x16
+* 32x32
+* 256x256
 
 ## High Resolution Image
 
diff --git a/docs/api/tray.md b/docs/api/tray.md
index 3fa6f606e90a..4c4891ef8960 100644
--- a/docs/api/tray.md
+++ b/docs/api/tray.md
@@ -29,6 +29,7 @@ __Platform limitations:__
 * When app indicator is used on Linux, the `click` event is ignored.
 * On Linux in order for changes made to individual `MenuItem`s to take effect,
   you have to call `setContextMenu` again. For example:
+* On Windows it is recommended to use `ICO` icons to get best visual effects.
 
 ```javascript
 contextMenu.items[2].checked = false;