diff --git a/docs/README.md b/docs/README.md
index c0a5855..dcebc84 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,14 +7,14 @@
 ![Maintainability Score](https://img.shields.io/codeclimate/maintainability/sagalbot/vue-select.svg?style=flat-square) 
 ![MIT License](https://img.shields.io/github/license/sagalbot/vue-select.svg?style=flat-square) 
 
-> Everything you wish the native `<select>` element could do, wrapped 
+> Everything you wish the HTML `<select>` element could do, wrapped 
 up into a zero dependency, highly extensible Vue component. 
 
 Vue Select is a feature rich select/dropdown/typeahead component. It provides a default
 template that fits the 80% use case for a select dropdown. Here it is by default:
 
-<div style="max-width:50%; margin: 0 auto; padding: 1rem 0;">
-  <v-select :options="['Option One','Option Two','Option Three']" />
+<div style="max-width:25rem; margin: 0 auto; padding: 1rem 0;">
+  <country-select />  
 </div>
 
 If you want to get a quick sense of what vue-select can do, check out
diff --git a/docs/api/props.md b/docs/api/props.md
index 052ed7e..f654b68 100644
--- a/docs/api/props.md
+++ b/docs/api/props.md
@@ -14,7 +14,7 @@ value: {
 
 An array of strings or objects to be used as dropdown choices.
 If you are using an array of objects, vue-select will look for
-a `label` key (ex. `[{label: 'This is Foo', value: 'foo'}]`). A
+a `label` key (ex. `[{label: 'Canada', value: 'CA'}]`). A
 custom label key can be set with the `label` prop.
 
 ```js
diff --git a/docs/guide/options.md b/docs/guide/options.md
index 4cab97c..a7bca73 100644
--- a/docs/guide/options.md
+++ b/docs/guide/options.md
@@ -4,17 +4,17 @@
 
 ```html
 <!-- array of strings or numbers -->
-<v-select :options="['foo','bar']"></v-select>
+<v-select :options="['Canada', 'United States']"></v-select>
 ```
 
-<v-select :options="['foo','bar']"></v-select>
+<v-select :options="['Canada', 'United States']"></v-select>
 
 ```html
 <!-- or, an array of objects -->
-<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
+<v-select :options="[{label: 'Canada', code: 'ca'}]"></v-select>
 ```
 
-<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
+<v-select :options="[{label: 'Canada', code: 'ca'}]"></v-select>
 
 ## Option Labels
 
@@ -52,14 +52,3 @@ If you wanted to display `Canada` in the dropdown, you'd use the `countryName` k
 `vue-select` requires the `options` prop to be an `array`. If you are using Vue in development 
 mode, you will get warnings attempting to pass anything other than an `array` to the `options` prop. 
 If you need a `null`/`empty` value, use an empty array `[]`.
-
-## Tagging
-
-To allow input that's not present within the options, set the `taggable` prop to true.
-If you want new tags to be pushed to the options list, set `push-tags` to true.
-
-```html
-<v-select taggable multiple push-tags />
-```
-
-<v-select taggable multiple push-tags />
diff --git a/docs/guide/values.md b/docs/guide/values.md
index 110e392..ec2d655 100644
--- a/docs/guide/values.md
+++ b/docs/guide/values.md
@@ -60,21 +60,29 @@ methods: {
 ```
 ## Transforming Selections
 
-When the `options` array contains objects, vue-select returns the whole object as dropdown value upon selection.
+When the `options` array contains objects, vue-select returns the whole object as dropdown value 
+upon selection. This approach makes no assumptions about the data you need, and provides a lot of
+flexibility. However, there will be situations where maybe you just need to return a single key
+from an object.
 
-If you need to return a single key, or transform the data before it is synced, vue-select provides a `reduce` callback
- that allows you to transform a selected option before it is passed to the `@input` event. Consider this data structure:
+### Returning a single key with `reduce`  
+
+If you need to return a single key, or transform the selection before it is synced, vue-select 
+provides a `reduce` callback that allows you to transform a selected option before it is passed to 
+the `@input` event. Consider this data structure:
  
  ```js
- let options = [{code: 'CA', country: 'Canada'}, ...];
+ let options = [{code: 'CA', country: 'Canada'}];
  ```
  
- If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce` prop to receive
- only the data that's required.
+If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce` 
+prop to receive only the data that's required.
  
  ```html
  <v-select :options="options" :reduce="country => country.code" label="country" />
  ```
+
+### Deep Nested Values
  
 The `reduce` property also works well when you have a deeply nested value:
  
@@ -82,26 +90,45 @@ The `reduce` property also works well when you have a deeply nested value:
  {
    country: 'canada',
    meta: {
-     id: '1',
      code: 'ca'
+     provinces: [...],
    }
  }
  ```
  
  ```html
- <v-select :options="options" :reduce="country => country.value.id" label="country" />
+ <v-select :options="options" :reduce="country => country.meta.code" label="country" />
  ```
  
  <reducer-nested-value />
 
 ## Single/Multiple Selection
 
-By default, vue-select supports choosing a single value. If you need multiple values, use the `multiple` boolean prop,
-much the same way you would on a native `<select>` element. When `multiple` is true, `v-model` or `value` should be
-arrays.
+By default, vue-select supports choosing a single value. If you need multiple values, use the 
+`multiple` boolean prop, much the same way you would on an HTML `<select>` element. When `multiple` 
+is true, `v-model` and `value` must be an array.
  
 
 ```html
-<v-select multiple v-model="selected" :options="['foo','bar']" />
+<v-select multiple v-model="selected" :options="['Canada','United States']" />
 ```
-<v-select multiple :options="['foo','bar']" />
+<v-select multiple :options="['Canada','United States']" />
+
+## Tagging
+
+To allow input that's not present within the options, set the `taggable` prop to true.
+
+```html
+<v-select taggable multiple />
+```
+
+<v-select taggable multiple />
+
+If you want added tags to be pushed to the options array, set `push-tags` to true.
+
+```html
+<v-select taggable multiple />
+```
+
+<v-select taggable multiple push-tags />
+