electron · zcbenz · Oct 23, 2020 · Oct 16, 2020 · Oct 20, 2020 · Oct 20, 2020
diff --git a/docs/images/dock-progress-bar.png b/docs/images/dock-progress-bar.png
diff --git a/docs/images/linux-progress-bar.png b/docs/images/linux-progress-bar.png
diff --git a/docs/images/macos-progress-bar.png b/docs/images/macos-progress-bar.png
diff --git a/docs/images/mission-control-progress-bar.png b/docs/images/mission-control-progress-bar.png
diff --git a/docs/tutorial/progress-bar.md b/docs/tutorial/progress-bar.md
@@ -1,35 +1,69 @@
 # Progress Bar in Taskbar (Windows, macOS, Unity)
 
-On Windows a taskbar button can be used to display a progress bar. This enables
-a window to provide progress information to the user without the user having to
-switch to the window itself.
+## Overview
 
-On macOS the progress bar will be displayed as a part of the dock icon.
+A progress bar enables a window to provide progress information to the user
+without the need of switching to the window itself.
 
-The Unity DE also has a similar feature that allows you to specify the progress
-bar in the launcher.
+On Windows, you can use a taskbar button to display a progress bar.
 
-__Progress bar in taskbar button:__
+![Windows Progress Bar][windows-progress-bar]
 
-![Taskbar Progress Bar][taskbar-progress-image]
+On macOS, the progress bar will be displayed as a part of the dock icon.
 
-All three cases are covered by the same API - the `setProgressBar()` method
-available on instances of `BrowserWindows`. Call it with a number between `0`
-and `1` to indicate your progress. If you have a long-running task that's
-currently at 63% towards completion, you'd call it with `setProgressBar(0.63)`.
+![macOS Progress Bar][macos-progress-bar]
 
-Generally speaking, setting the parameter to a value below zero (like `-1`)
-will remove the progress bar while setting it to a value higher than one
-(like `2`) will switch the progress bar to intermediate mode.
+On Linux, the Unity graphical interface also has a similar feature that allows
+you to specify the progress bar in the launcher.
+
+![Linux Progress Bar][linux-progress-bar]
+
+> NOTE: on Windows, each window can have its own progress bar, whereas on macOS
+and Linux (Unity) there can be only one progress bar for the application.
+
+----
+
+All three cases are covered by the same API - the
+[`setProgressBar()`][setprogressbar] method available on an instance of
+`BrowserWindow`. To indicate your progress, call this method with a number
+between `0` and `1`. For example, if you have a long-running task that is
+currently at 63% towards completion, you would call it as
+`setProgressBar(0.63)`.
+
+Setting the parameter to negative values (e.g. `-1`) will remove the progress
+bar, whereas setting it to values greater than `1` (e.g. `2`) will switch the
+progress bar to indeterminate mode (Windows-only -- it will clamp to 100%
+otherwise). In this mode, a progress bar remains active but does not show an
+actual percentage. Use this mode for situations when you do not know how long
+an operation will take to complete.
 
 See the [API documentation for more options and modes][setprogressbar].
 
+## Example
+
+Starting with a working application from the
+[Quick Start Guide](quick-start.md), add the following lines to the
+`main.js` file:
+
 ```javascript
 const { BrowserWindow } = require('electron')
 const win = new BrowserWindow()
 
 win.setProgressBar(0.5)
 ```
 
-[taskbar-progress-image]: https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png
+After launching the Electron application, you should see the bar in
+the dock (macOS) or taskbar (Windows, Unity), indicating the progress
+percentage you just defined.
+
+![macOS dock progress bar](../images/dock-progress-bar.png)
+
+For macOS, the progress bar will also be indicated for your application
+when using [Mission Control](https://support.apple.com/en-us/HT204100):
+
+![Mission Control Progress Bar](../images/mission-control-progress-bar.png)
+
+[windows-progress-bar]: https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png
+[macos-progress-bar]: ../images/macos-progress-bar.png
+[linux-progress-bar]: ../images/linux-progress-bar.png
 [setprogressbar]: ../api/browser-window.md#winsetprogressbarprogress-options