Meggin · dgash · Feb 9, 2016
diff --git a/builtins/amp-ad.md b/builtins/amp-ad.md
@@ -1,13 +1,10 @@
-### <a name="amp-ad"></a> `amp-ad`
+## <a name="amp-ad"></a> `amp-ad`
 
-NOTE: The specification of `amp-ad` is likely to significantly evolve over time. The current approach is designed to bootstrap the format to be able to show ads.
+**Note:** The specification of `amp-ad` is likely to significantly evolve over time. The current approach is designed to bootstrap the format to be able to show ads.
 
 A container to display an ad.
 
-Ads are loaded like all other resources in AMP documents, with a special
-custom element called `<amp-ad>`. No ad network provided JavaScript is allowed to run inside the AMP document. Instead the AMP runtime loads an iframe from a
-different origin (via iframe sandbox) as the AMP document and executes the ad
-network’s JS inside that iframe sandbox.
+Ads are loaded like all other resources in AMP documents, with a special custom element called `<amp-ad>`. No ad network is required, provided that JavaScript is allowed to run inside the AMP document. Instead, the AMP runtime loads an iframe from a different origin (via an iframe sandbox) as the AMP document, and executes the ad network’s JS inside that iframe sandbox.
 <!---
 Copyright 2015 The AMP HTML Authors. All Rights Reserved.
 
@@ -26,10 +23,10 @@ limitations under the License.
 
 AMP documents only support ads served via HTTPS.
 
-#### Behavior
+### Behavior
+
+The `<amp-ad>` component requires `width` and `height` values to be specified, as do all resources in AMP. It requires a `type` argument that selects which ad network is displayed. All `data-*` attributes on the tag are automatically passed as arguments to the code that eventually renders the ad. Which `data-` attributes are required for a given type of ad network depends on the network and must be documented with the network.
 
-The `<amp-ad>` requires width and height values to be specified like all
-resources in AMP. It requires a `type` argument that select what ad network is displayed. All `data-*` attributes on the tag are automatically passed as arguments to the code that eventually renders the ad. What `data-` attributes are required for a given type of network depends and must be documented with the ad network.
 ```html
 <amp-ad width=300 height=250
     type="a9"
@@ -39,7 +36,7 @@ resources in AMP. It requires a `type` argument that select what ad network is d
 </amp-ad>
 ```
 
-#### Supported ad networks
+### Supported ad networks
 
 - [A9](../ads/a9.md)
 - [Adform](../ads/adform.md)
@@ -51,75 +48,73 @@ resources in AMP. It requires a `type` argument that select what ad network is d
 - [plista](../ads/plista.md)
 - [Smart AdServer](../ads/smartadserver.md)
 
-#### Styling
+### Styling
 
-`<amp-ad>` elements may not themselves have or be placed in containers that have CSS `position: fixed` set (with the exception of `amp-lightbox`).
-This is due to the UX implications of full page overlay ads. It may be considered to allow similar ad formats in the future inside of AMP controlled containers that maintain certain UX invariants.
+`<amp-ad>` elements, with the exception of `amp-lightbox`, may not have or be placed in containers that have CSS `position: fixed` set. This is due to the UX implications of full-page overlay ads. In the future it may be considered to allow similar ad formats inside of AMP-controlled containers that maintain certain UX invariants.
 
-#### Attributes
+### Attributes
 
-##### type
+#### type
 
 Identifier for the ad network. This selects the template that is used for the ad tag.
 
-##### src
+#### src
+
+Optional `src` value for a script tag loaded for this ad network. This can be used with ad networks that require exactly a single script tag to be inserted into the page. The value must have a prefix that is whitelisted for this ad network.
 
-Optional src value for a script tag loaded for this ad network. This can be used with ad networks that require exactly a single script tag to be inserted in the page. The src value must have a prefix that is whitelisted for this ad network.
+#### data-foo-bar
 
-##### data-foo-bar
+Most ad networks require further configuration. This can be passed to the network using HTML `data-` attributes. The parameter names are subject to standard data attribute dash-to-camel-case conversion, e.g., "data-foo-bar" is sent to the ad for configuration as "fooBar".
 
-Most ad networks require further configuration. This can be passed to the network using HTML `data-` attributes. The parameter names are subject to standard data attribute dash to camel case conversion. E.g. "data-foo-bar" is send to the ad for configuration as "fooBar".
+#### json
 
-##### json
+Optional attribute to pass configuration to the ad as an arbitrarily complex JSON object. The object is passed to the ad as is, with no mangling done on the names.
 
-Optional attribute to pass configuration to the ad as an arbitrarily complex JSON object. The object is passed to the ad as-is with no mangling done on the names.
+#### data-consent-notification-id
 
-##### data-consent-notification-id
+Optional attribute. If provided, it requires confirming the [amp-user-notification](../extensions/amp-user-notification/amp-user-notification.md) with the given HTML-ID until the "AMP client id" for the user (similar to a cookie) is passed to the ad. The means ad rendering is delayed until the user confirms the notification.
 
-Optional attribute. If provided will require confirming the [amp-user-notification](../extensions/amp-user-notification/amp-user-notification.md) with the given HTML-id until the "AMP client id" for the user (similar to a cookie) is passed to the ad. The means ad rendering is delayed until the user confirmed the notification.
+### Placeholder
 
-#### Placeholder
+Optionally, `amp-ad` supports a child element with the `placeholder` attribute. If supported by the ad network, this element is shown until the ad is available for viewing.
 
-Optionally `amp-ad` supports a child element with the `placeholder` attribute. If supported by the ad network, this element is shown until the ad is available for viewing.
 ```html
 <amp-ad width=300 height=250
     type="foo">
   <div placeholder>Have a great day!</div>
 </amp-ad>
 ```
 
-#### No Ad available
-- `amp-ad` supports a child element with the `fallback` attribute. If supported by the ad network, this element is shown if no ad is available for this slot.
+#### No ad available
+
+`amp-ad` supports a child element with the `fallback` attribute. If supported by the ad network, this element is shown if no ad is available for this slot.
+
 ```html
 <amp-ad width=300 height=250
     type="foo">
   <div fallback>Have a great day!</div>
 </amp-ad>
 ```
 
-- If there is no fallback element available, the amp-ad tag will be collapsed (set to display: none) if the ad sends a message that the ad slot cannot be filled and AMP determines that this operation can be performed without affecting the user's scroll position.
+If there is no fallback element available, the amp-ad tag is collapsed (set to `display: none`) if the ad sends a message that the ad slot cannot be filled and AMP determines that this operation can be performed without affecting the user's scroll position.
 
-#### Running ads from a custom domain
+### Running ads from a custom domain
 
-AMP supports loading the bootstrap iframe that is used to load ads from a custom domain such as your own domain.
-
-To enable this, copy the file [remote.html](../3p/remote.html) to your web server. Next up add the following meta tag to your AMP file(s):
+AMP supports loading the bootstrap iframe that is used to load ads from a custom domain, such as your own domain. To enable this, copy the file [remote.html](../3p/remote.html) to your web server, then add the following meta tag to your AMP file(s):
 
 ```html
 <meta name="amp-3p-iframe-src" content="https://assets.your-domain.com/path/to/remote.html">
 ```
 
-The `content` attribute of the meta tag is the absolute URL to your copy of the remote.html file on your web server. This URL must use a "https" schema. It is not allowed to reside on the same origin as your AMP files. E.g. if you host AMP files on "www.example.com", this URL must not be on "www.example.com" but e.g. "something-else.example.com" is OK. See the doc ["Iframe origin policy"](../spec/amp-iframe-origin-policy.md) for further details on allowed origins for iframes.
-
-##### Enhance incoming ad configuration
+The `content` attribute of the meta tag is the absolute URL to your copy of the `remote.html` file on your web server. This URL must use the "https" schema. It is not allowed to reside on the same origin as your AMP files, e.g., if you host AMP files on "www.example.com", this URL must not be on "www.example.com", but "something-else.example.com" is allowed. See the doc ["Iframe origin policy"](../spec/amp-iframe-origin-policy.md) for further details on allowed origins for iframes.
 
-This is completely optional: It is sometimes desired to further process the incoming iframe configuration before drawing the ad using AMP's built-in system.
+### Enhance incoming ad configuration
 
-This is supported by passing a callback to the `draw3p` function call in the [remote.html](../3p/remote.html) file. The callback receives the incoming configuration as first argument and then receives another callback as second argument (Called `done` in the example below). This callback must be called with the updated config in order for ad rendering to proceed.
+This is completely optional. It is sometimes desirable to further process the incoming iframe configuration before drawing the ad using AMP's built-in system.
 
-Example:
+This is supported by passing a callback to the `draw3p` function call in the [remote.html](../3p/remote.html) file. The callback receives the incoming configuration as the first argument and then receives another callback as second argument (called `done` in the example below). This callback must be called with the updated config in order for ad rendering to proceed.
 
-```JS
+```javascript
 draw3p(function(config, done) {
   config.targeting = Math.random() > 0.5 ? 'sport' : 'fashion';
   // Don't actually call setTimeout here. This should only serve as an
@@ -128,3 +123,4 @@ draw3p(function(config, done) {
     done(config);
   }, 100)
 });
+```