diff --git a/Documentation/cloud-config.md b/Documentation/cloud-config.md
index 5e2de40..227d097 100644
--- a/Documentation/cloud-config.md
+++ b/Documentation/cloud-config.md
@@ -11,9 +11,7 @@ Only a subset of [cloud-config functionality][cloud-config] is implemented. A se
 ### coreos.etcd
 
 The `coreos.etcd.*` options are translated to a partial systemd unit acting as an etcd configuration file.
-`coreos-cloudinit` will also replace the strings `$private_ipv4` and `$public_ipv4` with the values generated by CoreOS based on a given provider.
-
-For example, the following cloud-config document...
+We can use the templating feature of coreos-cloudinit to automate etcd configuration with the `$private_ipv4` and `$public_ipv4` fields. For example, the following cloud-config document...
 
 ```
 #cloud-config
diff --git a/README.md b/README.md
index b2ca3b1..24b09eb 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,6 @@ write_files:
         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.
@@ -44,3 +43,37 @@ Make sure the first line of your user-data is a shebang and coreos-cloudinit wil
 
 echo 'Hello, world!'
 ```
+
+## user-data Field Substitution
+
+coreos-cloudinit will replace the following set of tokens in your user-data with system-generated values.
+
+| Token         | Description |
+| ------------- | ----------- |
+| $public_ipv4  | Public IPv4 address of machine |
+| $private_ipv4 | Private IPv4 address of machine |
+
+These values are determined by CoreOS based on the given provider on which your machine is running.
+Read more about provider-specific functionality in the [CoreOS OEM documentation][oem-doc].
+
+[oem-doc]: https://coreos.com/docs/sdk-distributors/distributors/notes-for-distributors/
+
+For example, submitting the following user-data...
+
+```
+#cloud-config
+coreos:
+    etcd:
+        addr: $public_ipv4:4001
+        peer-addr: $private_ipv4:7001
+```
+
+...will result in this cloud-config document being executed:
+
+```
+#cloud-config
+coreos:
+    etcd:
+        addr: 203.0.113.29:4001
+        peer-addr: 192.0.2.13:7001
+```
\ No newline at end of file