diff --git a/Documentation/cloud-config.md b/Documentation/cloud-config.md
index 86eb9a8..341328c 100644
--- a/Documentation/cloud-config.md
+++ b/Documentation/cloud-config.md
@@ -187,13 +187,3 @@ Provide a list of objects with the following attributes:
 - **content**: Data to write at the provided `path`
 - **permissions**: String representing file permissions in octal notation (i.e. '0644')
 - **owner**: User and group that should own the file written to disk. This is equivalent to the `<user>:<group>` argument to `chown <user>:<group> <path>`.
-
-## user-data Script
-
-Simply set your user-data to a script where the first line is a shebang:
-
-```
-#!/bin/bash
-
-echo 'Hello, world!'
-```
diff --git a/README.md b/README.md
index 23c799b..b2ca3b1 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,46 @@
 # coreos-cloudinit
 
-coreos-cloudinit enables a user to customize CoreOS machines by providing either an executable script or a cloud-config document as instance user-data.
+coreos-cloudinit enables a user to customize CoreOS machines by providing either a cloud-config document or an executable script through user-data.
 
-## Supported Cloud-Config Features
+## Configuration with cloud-config
 
-A subset of [cloud-config][cloud-config] is implemented in coreos-cloudinit and is [documented here](https://github.com/coreos/coreos-cloudinit/tree/master/Documentation/cloud-config.md). In addition specific CoreOS paramaters were added for unit files, etcd discovery urls, and others.
+A subset of the [official cloud-config spec][official-cloud-config] is implemented by coreos-cloudinit.
+Additionally, several [CoreOS-specific options][custom-cloud-config] have been implemented to support interacting with unit files, bootstrapping etcd clusters, and more.
+All supported cloud-config parameters are [documented here][all-cloud-config]. 
 
-[cloud-config]: http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data
+[official-cloud-config]: http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data
+[custom-cloud-config]: https://github.com/coreos/coreos-cloudinit/blob/master/Documentation/cloud-config.md#coreos-parameters
+[all-cloud-config]: https://github.com/coreos/coreos-cloudinit/tree/master/Documentation/cloud-config.md
+
+The following is an example cloud-config document:
+
+```
+#cloud-config
+
+coreos:
+    units:
+      - name: etcd.service
+        command: start
+
+users:
+  - name: core
+    passwd: $1$allJZawX$00S5T756I5PGdQga5qhqv1
+
+write_files:
+  - path: /etc/resolv.conf
+    content: |
+        nameserver 192.0.2.2
+        nameserver 192.0.2.3
+```
+
+
+## Executing a Script
+
+coreos-cloudinit supports executing user-data as a script instead of parsing it as a cloud-config document.
+Make sure the first line of your user-data is a shebang and coreos-cloudinit will attempt to execute it:
+
+```
+#!/bin/bash
+
+echo 'Hello, world!'
+```