Revamp standalone documentation

docs/standalone.md

@@ -4,16 +4,20 @@ title: @babel/standalone
 sidebar_label: standalone
 ---
 
+@babel/standalone provides a standalone build of Babel for use in browsers and other non-Node.js environments.
 
-But why?!
-=========
+When (not) to use @babel/standalone
+===================================
 
-It's true that using Babel through Webpack, Browserify or Gulp should be sufficient for most use cases. However, there are some valid use cases for @babel/standalone:
+If you're using Babel in production, you should normally not use @babel/standalone. Instead, you should use a build system running on Node.js, such as Webpack, Rollup, or Parcel, to transpile your JS ahead of time.
 
- - Sites like [JSFiddle](https://jsfiddle.net/), [JS Bin](https://jsbin.com/), the [REPL on the Babel site](http://babeljs.io/repl/), [JSitor](https://jsitor.com), etc. These sites compile user-provided JavaScript in real-time.
- - Apps that embed a JavaScript engine such as V8 directly, and want to use Babel for compilation
-  - Apps that want to use JavaScript as a scripting language for extending the app itself, including all the goodies that ES2015 provides.
-  - Integration of Babel into a non-Node.js environment ([ReactJS.NET](http://reactjs.net/), [ruby-babel-transpiler](https://github.com/babel/ruby-babel-transpiler), [php-babel-transpiler](https://github.com/talyssonoc/php-babel-transpiler), etc).
+However, there are some valid use cases for @babel/standalone:
+
+- It provides an easy, convenient way to prototype with Babel. Using @babel/standalone, you can get started using Babel with just a simple script tag in your HTML.
+- Sites that compile user-provided JavaScript in real-time, like [JSFiddle](https://jsfiddle.net/), [JS Bin](https://jsbin.com/), the [REPL on the Babel site](http://babeljs.io/repl/), [JSitor](https://jsitor.com), etc.
+- Apps that embed a JavaScript engine such as V8 directly, and want to use Babel for compilation
+- Apps that want to use JavaScript as a scripting language for extending the app itself, including all the goodies that ES2015 provides.
+- Other non-Node.js environments ([ReactJS.NET](http://reactjs.net/), [ruby-babel-transpiler](https://github.com/babel/ruby-babel-transpiler), [php-babel-transpiler](https://github.com/talyssonoc/php-babel-transpiler), etc).
 
 Installation
 ============
@@ -25,17 +29,11 @@ There are several ways to get a copy of @babel/standalone. Pick whichever one yo
 - Manually grab `babel.js` and/or `babel.min.js` from the [GitHub releases page](https://github.com/Daniel15/babel-standalone/releases). Every release includes these files.
 - Install it via Git: You can use the repo at https://github.com/Daniel15/babel-standalone-bower to pull a prebuilt version from Git. Note that this is generally only advised for systems that *must* pull artifacts from Git, such as Bower.
 
-Usage
-=====
-
-Load `babel.js` or `babel.min.js` in your environment. This will expose [Babel's API](http://babeljs.io/docs/usage/api/) in a `Babel` object:
-
-```js
-var input = 'const getMessage = () => "Hello World";';
-var output = Babel.transform(input, { presets: ['env'] }).code;
-```
+Script Tags
+===========
 
 When loaded in a browser, @babel/standalone will automatically compile and execute all script tags with type `text/babel` or `text/jsx`:
+
 ```html
 <div id="output"></div>
 <!-- Load Babel -->
@@ -47,16 +45,40 @@ document.getElementById('output').innerHTML = getMessage();
 </script>
 ```
 
+If you want to use your browser's native support for ES Modules, you'd normally need to set a `type="module"` attribute on your script tag. With @babel/standalone, set a `data-type="module"` attribute instead, like this:
+
+```html
+<script type="text/babel" data-type="module">
+```
+
 You can use the `data-plugins` and `data-presets` attributes to specify the Babel plugins/presets to use:
+
 ```html
 <script type="text/babel" data-presets="env,stage-3">
 ```
 
 Loading external scripts via `src` attribute is supported too:
+
 ```html
 <script type="text/babel" src="foo.js"></script>
 ```
 
+You can also set the `async` attribute for external scripts.
+
+```html
+<script type="text/babel" src="foo.js" async></script>
+```
+
+API
+===
+
+Load `babel.js` or `babel.min.js` in your environment. This will expose [Babel's API](http://babeljs.io/docs/usage/api/) in a `Babel` object:
+
+```js
+var input = 'const getMessage = () => "Hello World";';
+var output = Babel.transform(input, { presets: ['env'] }).code;
+```
+
 Note that [config files](config-files.md) don't work in @babel/standalone, as no file system access is available. The presets and/or plugins to use **must** be specified in the options passed to `Babel.transform`.
 
 Customisation
@@ -77,7 +99,13 @@ function lolizer() {
 Babel.registerPlugin('lolizer', lolizer);
 ```
 
-Once registered, just use the name of the plugin:
+Once registered, you can either use the custom plugin in an inline script:
+
+```html
+<script type="text/babel" data-plugins="lolizer">
+```
+
+Or you can use the plugin with `Babel.transform`:
 
 ```js
 var output = Babel.transform(
@@ -86,10 +114,3 @@ var output = Babel.transform(
 );
 // Returns "function LOL() { LOL(LOL); }"
 ```
-
-Custom plugins also work for inline `<script>`s:
-
-```html
-<script type="text/babel" data-plugins="lolizer">
-```
-