docs wip

docs/en/README.md

@@ -1,22 +1,13 @@
 ## What is Vuex?
 
-A state management library.
+Vuex is an application architecture for centralized state management in Vue.js applications. It is inspired by [Flux](https://facebook.github.io/flux/) and [Redux](https://github.com/rackt/redux), but with simplified concepts and an implementation that is designed specifically to take advantage of Vue.js' reactivity system.
 
-And an application architecture for Vue.js.
+## Why do I need this?
 
-## Principles
+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.
 
-- Terse
-- Testable
-- Reactive
-- Single State Tree
-- Hot Reloading
-- Time Travel
+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.
 
-## Difference from Redux/Flux
+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.
 
-- Simplified concepts.
-
-- Specifically built for Vue.js, therefore reactive by default. Super simple for components to bind to state.
-
-- Doesn't enforce immutability, but retains the same benefits of hot reloading and time travel debugging.
+Vuex also enforces some opinions on how to split state management logic into different places, but still allows enough flexibility for the actual code structure.

docs/en/SUMMARY.md

@@ -1,8 +1,12 @@
 - [Core Concepts](concepts.md)
   - [State](state.md)
-  - [Actions](actions.md)
   - [Mutations](mutations.md)
+  - [Actions](actions.md)
+- [Data Flow](data-flow.md)
 - [Application Structure](structure.md)
 - [Debug Mode](debug.md)
+- [Form Handling](forms.md)
 - [Middlewares](middlewares.md)
+- [Testing](testing.md)
 - [Hot Reloading](hot-reload.md)
+- [API Reference](api.md)

docs/en/concepts.md

@@ -0,0 +1,31 @@
+## Core Concepts
+
+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:
+
+- **State**: A plain object representing the state. Vuex uses a **single state tree** - that is, this single object contains all your application level state and serves as the "single source of truth". We will later discuss how to "split up" the logic for different parts of your app.
+
+- **Mutations**: Functions that mutates the state. Mutations **must be synchronous**.
+
+- **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.
+
+> 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*.
+
+### Putting it Together
+
+Creating a Vuex instance is pretty straightforward - just put the aforementioned ingredients together:
+
+``` js
+const vuex = new Vuex({
+  state: { ... },
+  actions: { ... },
+  mutations: { ... }
+})
+```
+
+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/)!