diff --git a/docs/core-tags.md b/docs/core-tags.md
index cf83611ff..11e4317e4 100644
--- a/docs/core-tags.md
+++ b/docs/core-tags.md
@@ -371,10 +371,49 @@ sample template shows how to use macro functions inside expressions:
 </p>
 ```
 
-## Awaiting promises
+## Async content
 
 ### `<await>`
 
+The `<await>` tag is used to dynamically load in content from a data provider. The data provider can be a `Promise` or a `callback`. Once the provider returns it's results the children are rendered.
+
+await-example.marko
+```xml
+$ var personPromise = new Promise((resolve, reject) => {
+    setTimeout(function() {
+        resolve({
+            name: 'Frank'
+        });
+    }, 1000);
+});
+
+<await(person from personPromise)>
+    <div>Hello ${person.name}!</div>
+</await>
+```
+
+Advanced implementation:
++ <await> tag signature
+  * Basic usage: <await(results from dataProvider)>...</await>
+  * Optional attributes (details below)
+    - client-reorder `boolean`
+    - arg `expression`
+    - arg-* `string`
+    - method `string`
+    - timeout `integer`
+    - timeout-message `string` 
+    - error-message `string`
+    - placeholder `string`
+    - renderTimeout `function`
+    - renderError `function`
+    - renderPlaceholder `function`
+    - name `string`
+    - scope `expression`
+    - show-after `string`
+  * Optional child tags
+    - <await-placeholder>Loading...</await-placeholder>
+    - <await-timeout>Request timed out</await-timeout>
+    - <await-error>Request errored</await-error>
 
 ## Comments