diff --git a/docs/api/desktop-capturer.md b/docs/api/desktop-capturer.md
index a72539a7a28..56b525a5198 100644
--- a/docs/api/desktop-capturer.md
+++ b/docs/api/desktop-capturer.md
@@ -1,7 +1,10 @@
 # desktopCapturer
 
-> List `getUserMedia` sources for capturing audio, video, and images from a
-microphone, camera, or screen.
+> Access information about media sources that can be used to capture audio and
+> video from the desktop using the [`navigator.webkitGetUserMedia`] API.
+
+The following example shows how to capture video from a desktop window whose
+title is `Electron`:
 
 ```javascript
 // In the renderer process.
@@ -23,29 +26,28 @@ desktopCapturer.getSources({types: ['window', 'screen']}, (error, sources) => {
             maxHeight: 720
           }
         }
-      }, gotStream, getUserMediaError);
+      }, handleStream, handleError);
       return;
     }
   }
 });
 
-function gotStream(stream) {
+function handleStream(stream) {
   document.querySelector('video').src = URL.createObjectURL(stream);
 }
 
-function getUserMediaError(e) {
-  console.log('getUserMediaError');
+function handleError(e) {
+  console.log(e);
 }
 ```
 
-When creating a constraints object for the `navigator.webkitGetUserMedia` call,
-if you are using a source from `desktopCapturer` your `chromeMediaSource` must
-be set to `"desktop"` and your `audio` must be set to `false`.
+To capture video from a source provided by `desktopCapturer` the constraints
+passed to [`navigator.webkitGetUserMedia`] must include
+`chromeMediaSource: 'desktop'`, and `audio: false`.
 
-If you wish to
-capture the audio and video from the entire desktop you can set
-`chromeMediaSource` to `"screen"` and `audio` to `true`. When using this method
-you cannot specify a `chromeMediaSourceId`.
+To capture both audio and video from the entire desktop the constraints passed
+to [`navigator.webkitGetUserMedia`] must include `chromeMediaSource: "screen"`,
+and `audio: true`, but should not include a `chromeMediaSourceId` constraint.
 
 ## Methods
 
@@ -56,24 +58,28 @@ The `desktopCapturer` module has the following methods:
 * `options` Object
   * `types` Array - An array of String that lists the types of desktop sources
     to be captured, available types are `screen` and `window`.
-  * `thumbnailSize` Object (optional) - The suggested size that thumbnail should
-    be scaled, it is `{width: 150, height: 150}` by default.
+  * `thumbnailSize` Object (optional) - The suggested size that the media source
+    thumbnail should be scaled to, defaults to `{width: 150, height: 150}`.
 * `callback` Function
 
-Starts a request to get all desktop sources, `callback` will be called with
-`callback(error, sources)` when the request is completed.
+Starts gathering information about all available desktop media sources,
+and calls `callback(error, sources)` when finished.
 
-The `sources` is an array of `Source` objects, each `Source` represents a
-captured screen or individual window, and has following properties:
+`sources` is an array of `Source` objects, each `Source` represents a
+screen or an individual window that can be captured, and has the following
+properties:
 
-* `id` String - The id of the captured window or screen used in
-  `navigator.webkitGetUserMedia`. The format looks like `window:XX` or
-  `screen:XX` where `XX` is a random generated number.
-* `name` String - The described name of the capturing screen or window. If the
-  source is a screen, the name will be `Entire Screen` or `Screen <index>`; if
-  it is a window, the name will be the window's title.
-* `thumbnail` [NativeImage](native-image.md) - A thumbnail native image.
+* `id` String - The identifier of a window or screen that can be used as a
+  `chromeMediaSourceId` constraint when calling
+  [`navigator.webkitGetUserMedia`]. The format of the identifier will be
+  `window:XX` or `screen:XX`, where `XX` is a random generated number.
+* `name` String - A screen source will be named either `Entire Screen` or
+  `Screen <index>`, while the name of a window source will match the window
+  title.
+* `thumbnail` [NativeImage](native-image.md) - A thumbnail image. **Note:**
+  There is no guarantee that the size of the thumbnail is the same as the
+  `thumnbailSize` specified in the `options` passed to
+  `desktopCapturer.getSources`. The actual size depends on the scale of the
+  screen or window.
 
-**Note:** There is no guarantee that the size of `source.thumbnail` is always
-the same as the `thumnbailSize` in `options`. It also depends on the scale of
-the screen or window.
+[`navigator.webkitGetUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/Navigator/getUserMedia