read-me-updates (mdn#441)

* read-me-updates

In addition to some general improvements to the text, this change focuses on adding notes about:
* checking the readme file for any limitations on domains or pages the extension works in
* the fact that no extension runs in a private window by default, with a link to related help article
* contacting the discourse forum as a first point of call for issues

* Minor changes from readthrough

README.md

@@ -5,14 +5,15 @@
 Maintained by the [MDN team at Mozilla](https://wiki.mozilla.org/MDN).
 
 WebExtensions are a way to write browser extensions: that is, programs
-installed inside a web browser that modify the behaviour of the browser or
-of web pages loaded by the browser. They are built on a set of
-cross-browser APIs, so WebExtensions written for Google Chrome or Opera will
-in most cases run in Firefox or Edge too.
+installed inside a web browser that modify the behavior of the browser or
+web pages loaded by the browser. WebExtensions are built on a set of
+cross-browser APIs, so WebExtensions written for Google Chrome, Opera, or 
+Edge will, in most cases, run in Firefox too.
 
-The "webextensions-examples" repository is a collection of simple but complete
-and installable WebExtensions. You can use the examples to see how to use the
-WebExtensions APIs, and as a starting point for your own WebExtensions.
+The "webextensions-examples" repository is a collection of simple, 
+complete, and installable WebExtensions. The examples show how to use the
+WebExtensions APIs, and you can use them as a starting point for your 
+WebExtensions.
 
 For an index of all the examples, see the ["Example extensions" page on MDN](https://developer.mozilla.org/Add-ons/WebExtensions/Examples).
 
@@ -23,45 +24,55 @@ The examples are made available under the
 
 To use the repository, first clone it.
 
-Each example is in its own top-level directory. Install an example in your
-favourite web browser ([installation instructions](#installing-an-example) are below),
-and see how it works. Each example has its own short README explaining what
-it does.
+Each example is in a top-level folder and includes a short README explaining
+what it does. To see how an example works, install it in Firefox by following 
+the ([installation instructions](#installing-an-example). 
 
 To find your way around a WebExtension's internal structure, have a look at the
 [Anatomy of a WebExtension](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension)
 page on MDN.
 
-To use these examples in Firefox, you should use the most recent release
-of Firefox. Some examples work with earlier releases.
+To use these examples in Firefox, use the most recent release of Firefox.
+However, most examples work with earlier releases.
 
-A few examples rely on APIs that are currently only available in pre-release
-versions of Firefox. Where this is the case, the example should declare
-the minimum version that it needs in the `strict_min_version` part of the
-[applications key](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/applications)
-in its manifest.json file.
+A few examples rely on APIs that are only available in pre-release versions 
+of Firefox. Where this is the case, the example declares the minimum version
+that it needs in the `strict_min_version` attribute of the
+[`browser_specific_settings key`](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/browser_specific_settings)
+in the extension's manifest.json file.
 
 ## Installing an example
 
-There are a couple ways to try out the example extensions in this repository.
+Some examples work only on specific domains or pages. Details of any 
+restrictions are provided in each example's README file. None of the 
+examples work in private browsing windows by default, see 
+[Extensions in Private Browsing](https://support.mozilla.org/en-US/kb/extensions-private-browsing#w_enabling-or-disabling-extensions-in-private-windows) 
+for details.
 
-1. Open Firefox and load `about:debugging` in the URL bar. Click the
+To run an example extension:
+
+1. Open Firefox and load the `about:debugging` page. Click 
    [Load Temporary Add-on](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Temporary_Installation_in_Firefox)
-   button and select the `manifest.json` file within the
-   directory of an example extension you'd like to install.
+   and select the `manifest.json` file within the folder of an example extension.
    Here is a [video](https://www.youtube.com/watch?v=cer9EUKegG4)
    that demonstrates how to do this.
 2. Install the
    [web-ext](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext)
-   tool, change into the directory of the example extension
-   you'd like to install, and type `web-ext run`. This will launch Firefox and
-   install the extension automatically. This tool gives you some
-   additional development features such as
+   tool. At the command line, open the example extension's folder and type
+   `web-ext run`. This launches Firefox and installs the extension automatically.
+   This tool provides some additional development features, such as
    [automatic reloading](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Getting_started_with_web-ext#Automatic_extension_reloading).
 
 ## Support for other browsers
 
-These examples are only tested in Firefox. They may work in other browsers, if the [browser supports the APIs used](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs). Note though that these examples all use the name `browser` for the namespace and use promises to work with asynchronous functions. This means the examples won't work in Chrome unless you use the [polyfill provided by Mozilla](https://github.com/mozilla/webextension-polyfill). See [the overview of WebExtension APIs](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API) for more information on this.
+These examples are tested in Firefox. They may work in other browsers, if the
+[browser supports the APIs used](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs).
+Note that these examples all use the `browser` namespace and promises to 
+work with asynchronous functions. This means the examples won't work in 
+Chrome unless you use the 
+[polyfill provided by Mozilla](https://github.com/mozilla/webextension-polyfill).
+See [the overview of WebExtension APIs](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API) 
+for more information.
 
 ## Learn more
 
@@ -71,12 +82,16 @@ for getting started guides, tutorials, and full API reference docs.
 
 ## Problems?
 
-If you find a problem, please [file a bug](https://github.com/mdn/webextensions-examples/issues/new).
+If you encounter an issue:
+- post a query on the [add-ons discourse forum](https://discourse.mozilla.org/c/add-ons)
+- email the [dev-addons mailing list](https://mail.mozilla.org/listinfo/dev-addons)
+- contact the WebExtensions team in the #webextensions IRC channel on irc.mozilla.org
 
-If you need help, email the [dev-addons mailing list](https://mail.mozilla.org/listinfo/dev-addons) or contact the WebExtensions team in the #webextensions IRC channel on irc.mozilla.org.
+If you cannot resolve the issue, [file a bug](https://github.com/mdn/webextensions-examples/issues/new).
 
 ## Contributing
 
-We welcome contributions, whether they are whole new examples, new features,
-bug fixes, or translations of localizable strings into new languages. Please
-see the [CONTRIBUTING.md](https://github.com/mdn/webextensions-examples/blob/master/CONTRIBUTING.md) file for more details.
+We welcome contributions, whether they are new examples, new features, bug 
+fixes, or translations of localizable strings. Please see the 
+[CONTRIBUTING.md](https://github.com/mdn/webextensions-examples/blob/master/CONTRIBUTING.md)
+file for more details.