update docs

README.md

@@ -2,6 +2,8 @@
 
 > Flux-inspired Application Architecture for Vue.js.
 
+![vuex](https://raw.githubusercontent.com/vuejs/vuex/master/docs/en/vuex.png)
+
 ## Principles
 
 - Terse

docs/book.json

@@ -9,5 +9,11 @@
     "github": {
       "url": "https://github.com/vuejs/vuex/"
     }
+  },
+  "links": {
+    "sharing": {
+      "facebook": false,
+      "twitter": false
+    }
   }
 }

docs/en/actions.md

@@ -81,6 +81,18 @@ actions: {
 }
 ```
 
+The string shorthand is essentially syntax sugar for the following:
+
+``` js
+actions: {
+  increment: 'INCREMENT'
+}
+// ... equivalent to:
+actions: {
+  increment: (...args) => dispatch => dispatch('INCREMENT', ...args)
+}
+```
+
 Why don't we just define the actions as simple functions that directly access `vuex.state` and `vuex.dispatch`? The reason is that couples the action functions to the specific vuex instance. By using the thunk syntax, our actions only depend on function arguments and nothing else - this important characteristic makes them easy to test and hot-reloadable!
 
 ### Async Actions

docs/en/concepts.md

@@ -2,7 +2,7 @@
 
 Similar to Vue itself, Vuex exposes a single `Vuex` constructor. You can use it to create **Vuex instances**. In most cases, you only need one Vuex instance for an app. You can think of a Vuex instance as an "enhanced store" that holds your app state.
 
-Each Vuex instance consists of three core parts:
+Each Vuex instance consists of three types of "ingredients":
 
 - **State**: A plain object representing the application state.
 
@@ -10,12 +10,14 @@ Each Vuex instance consists of three core parts:
 
 - **Actions**: Functions that dispatch mutations. An action can contain asynchronous operations and can dispatch multiple mutations.
 
-Why do we have mutations and actions, rather then just simple functions that manipulate the state however we want? The reason is because we want to **separate mutation and asynchronicity**. A lot of application complexity roots from the combination of the two. When separated, they both become easier to reason about and write tests for.
+Why do we differentiate between *mutations* and *actions*, rather then just simple functions that manipulate the state however we want? The reason is because we want to **separate mutation and asynchronicity**. A lot of application complexity roots from the combination of the two. When separated, they both become easier to reason about and write tests for.
 
-> If you are familiar with Flux, note there's a term/concept difference here: Vuex mutations are the equivalent of Flux *actions*, while Vuex actions are equivalent to Flux *action creators*.
+> If you are familiar with Flux, note there's a term/concept difference here: Vuex mutations are the equivalent of Flux **actions**, while Vuex actions are equivalent to Flux **action creators**.
 
 ### Creating a Vuex Instance
 
+> **NOTE:** We will be using ES2015 syntax for code examples for the rest of the docs. If you haven't picked it up, [you should](https://babeljs.io/docs/learn-es2015/)! The doc also assumes you are already familiar with the concepts discussed in [Building Large-Scale Apps with Vue.js](http://vuejs.org/guide/application.html).
+
 Creating a Vuex instance is pretty straightforward - just put the aforementioned ingredients together:
 
 ``` js
@@ -30,4 +32,3 @@ const vuex = new Vuex({
 
 Once created, you can access the state via `vuex.state`, and the actions via `vuex.actions`. You cannot directly access the mutation functions - they can only be triggered by actions or calling `vuex.dispatch()`. We will discuss each concept in more details next.
 
-> We will be using ES2015 syntax for code examples for the rest of the docs. If you haven't picked it up, [you should](https://babeljs.io/docs/learn-es2015/)!

docs/en/data-flow.md

@@ -0,0 +1,90 @@
+# Date Flow
+
+Let's build a simple counter app with Vuex to get a better understanding of the data flow inside Vuex apps. Note this is a trivial example solely for the purpose of explaining the concepts - in practice you don't need Vuex for such simple tasks.
+
+### Setup
+
+``` js
+// vuex.js
+import Vue from 'vue'
+import Vuex from 'vuex'
+
+Vue.use(Vuex)
+```
+
+### Define App State
+
+``` js
+const state = {
+  count: 0
+}
+```
+
+### Define Possible State Mutations
+
+``` js
+const mutations = {
+  INCREMENT (state) {
+    state.count++
+  },
+  DECREMENT (state) {
+    state.count--
+  }
+}
+```
+
+### Define Callable Actions
+
+``` js
+const actions = {
+  increment: 'INCREMENT',
+  decrement: 'DECREMENT'
+}
+```
+
+### Create a Vuex Instance
+
+``` js
+export default new Vuex({
+  state,
+  mutations,
+  actions
+})
+```
+
+### Use It in a Vue Component
+
+**Template**
+
+``` html
+<div>
+  Clicked: {{ count }} times
+  <button v-on:click="increment">+</button>
+  <button v-on:click="decrement">-</button>
+</div>
+```
+
+**Script**
+
+``` js
+import vuex from './vuex.js'
+
+export default {
+  computed: {
+    // bind to state using computed properties
+    count () {
+      return vuex.state.count
+    }
+  },
+  methods: {
+    increment: vuex.actions.increment,
+    decrement: vuex.actions.decrement
+  }
+}
+```
+
+Here you will notice the component itself is extremely simple: it simply displays some state from the Vuex instance (not even owning its own data), and calls some vuex actions on user input events.
+
+You will also notice the data flow is unidirectional, as it should be in Flux:
+
+![data-flow](vuex.png)

docs/en/intro.md

@@ -6,7 +6,7 @@ Vuex is an application architecture for centralized state management in Vue.js a
 
 If your app is simple enough, you probably don't need Vuex. Don't apply it prematurely. But if you are building a medium-to-large-scale SPA, chances are you have run into situations that make you think about how to better structure things outside of your Vue components. This is where Vuex comes into play.
 
-When using Vue.js alone, we often tend to store the state "inside" our components. That is, each component owns a piece of our application state, and as a result the state is scattered all over the place. However, sometimes a piece of state needs to be shared by multiple components. A commonly-seen practice is letting one component "send" some state to other components using the custom event system. However, the event flow inside large component trees can quickly become complex, and it's often difficult to reason about when something goes wrong.
+When using Vue.js alone, we often tend to store the state "inside" our components. That is, each component owns a piece of our application state, and as a result the state is scattered all over the place. However, sometimes a piece of state needs to be shared by multiple components. A commonly-seen practice is letting one component "send" some state to other components using the custom event system. The problem with this pattern is that the event flow inside large component trees can quickly become complex, and it's often difficult to reason about when something goes wrong.
 
 To better deal with shared state in large applications, we need to differentiate between **component local state** and **application level state**. Application state does not belong to a specific component, but our components can still observe it for reactive DOM updates. By centralizing its management in a single place, we no longer need to pass events around, because everything that affects more than one component should belong there. In addition, this allows us to record and inspect every mutation for easier understanding of state changes, and even implement fancy stuff like time-travel debugging.
 

docs/en/quickstart.md

@@ -0,0 +1,2 @@
+# Quickstart
+

docs/en/state.md

@@ -6,7 +6,7 @@ Vuex uses a **single state tree** - that is, this single object contains all you
 
 The single state tree does not conflict with modularity - in later chapters we will discuss how to split your state managing logic into sub modules.
 
-### Reactive State
+### Getting Vuex State into Vue Components
 
 Similar to `data` objects passed to Vue instances, the `state` object, once passed into a Vuex instance, becomes reactive powered by [Vue's reactivity system](http://vuejs.org/guide/reactivity.html). This means binding Vuex state to Vue components is as simple as returning it from within a computed property:
 
@@ -25,6 +25,8 @@ export default {
 }
 ```
 
+In order to ensure reactive updates, you should **always reference state via `vuex.state.xxx` inside your computed properties**. Do not cache the reference to a piece of state outside computed properties.
+
 > Flux reference: this can be roughly compared to [`mapStateToProps`](https://github.com/rackt/react-redux/blob/master/docs/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options) in Redux and [getters](https://optimizely.github.io/nuclear-js/docs/04-getters.html) in NuclearJS.
 
 Why don't we just use `data` to bind to vuex state? Consider the following example: