Merge pull request reduxjs#527 from webpro/docs

Docs

Author: gaearon

README.md

@@ -52,7 +52,7 @@ npm install --save-dev redux-devtools
 
 The whole state of your app is stored in an object tree inside a single *store*.  
 The only way to change the state tree is to emit an *action*, an object describing what happened.  
-To specify how the state tree is transformed by the actions, you write pure *reducers*.
+To specify how the actions transform the state tree, you write pure *reducers*.
 
 That’s it!
 
@@ -64,11 +64,11 @@ import { createStore } from 'redux';
  * It describes how an action transforms the state into the next state.
  *
  * The shape of the state is up to you: it can be a primitive, an array, an object,
- * or even an Immutable.js data structure. The only important part is you should
- * return a new object if the state changes, instead of mutating the parameter.
+ * or even an Immutable.js data structure. The only important part is that you should
+ * not mutate the state object, but return a new object if the state changes.
  *
  * In this example, we use a `switch` statement and strings, but you can use a helper that
- * follows a different convention (such as function maps) that makes sense for your project.
+ * follows a different convention (such as function maps) if it makes sense for your project.
  */
 function counter(state = 0, action) {
   switch (action.type) {
@@ -81,7 +81,7 @@ function counter(state = 0, action) {
   }
 }
 
-// Create a Redux store that holds the state of your app.
+// Create a Redux store holding the state of your app.
 // Its API is { subscribe, dispatch, getState }.
 let store = createStore(counter);
 
@@ -125,7 +125,7 @@ This architecture might seem like an overkill for a counter app, but the beauty
 
 ### Discussion
 
-Join the **#redux** channel of the [Reactiflux](http://reactiflux.com/) Slack community.
+Join the **#redux** channel of the [Reactiflux](http://reactiflux.com) Slack community.
 
 ### Thanks
 
@@ -140,7 +140,7 @@ Join the **#redux** channel of the [Reactiflux](http://reactiflux.com/) Slack co
 * [Cycle](https://github.com/staltz/cycle) for showing how often a function is the best tool;
 * [React](https://github.com/facebook/react) for the pragmatic innovation.
 
-Special thanks to [Jamie Paton](http://jdpaton.github.io/) for handing over the `redux` NPM package name.
+Special thanks to [Jamie Paton](http://jdpaton.github.io) for handing over the `redux` NPM package name.
 
 ### Patrons
 

docs/advanced/Middleware.md

@@ -316,10 +316,7 @@ import { createStore, combineReducers, applyMiddleware } from 'redux';
 
 // applyMiddleware takes createStore() and returns
 // a function with a compatible API.
-let createStoreWithMiddleware = applyMiddleware(
-  logger,
-  crashReporter
-)(createStore);
+let createStoreWithMiddleware = applyMiddleware(logger, crashReporter)(createStore);
 
 // Use it like you would use createStore()
 let todoApp = combineReducers(reducers);

docs/introduction/Motivation.md

@@ -1,11 +1,11 @@
 # Motivation
 
-As the requirements to JavaScript single-page applications get more sophisticated, **more state than ever before needs to be managed by the JavaScript code.** This state may include server responses, cached data, and data created locally, but not yet persisted to the server. It also includes the UI state, such as the active route, the selected tab, whether to show a spinner or pagination controls, and so on.
+As the requirements to JavaScript single-page applications get more sophisticated, **more state needs to be managed** by the JavaScript code than ever before. This state may include server responses, cached data, and data created locally, but not yet persisted to the server. It also includes the UI state, such as the active route, the selected tab, whether to show a spinner or pagination controls, and so on.
 
 Managing ever-changing state is hard. If a model can update another model, then a view can update a model that updates another model, and this, in turn, might cause another view to update. At some point you no longer know what happens in your app. **You no longer control when, why, and how the state is updated.** When the system is opaque and non-deterministic, it’s hard to reproduce bugs or add new features.
 
-As if this wasn’t bad enough, consider the **new requirements that are becoming common in front-end product development**, such as handling optimistic updates, rendering on the server, fetching the data before performing route transitions, and so on. We the front-end developers are finding ourselves surrounded by complexity we never had to deal with before. [Is it time we give up?](http://www.quirksmode.org/blog/archives/2015/07/stop_pushing_th.html)
+As if this wasn’t bad enough, consider the **new requirements becoming common in front-end product development**, such as handling optimistic updates, rendering on the server, fetching data before performing route transitions, and so on. We the front-end developers are finding ourselves surrounded by the complexity we never had to deal with before. [Is it time we give up?](http://www.quirksmode.org/blog/archives/2015/07/stop_pushing_th.html)
 
-A lot of this complexity comes from the fact that **we’re mixing two concepts that are very hard for the human mind to reason about: mutation and asynchronicity.** I call them [Mentos and Coke](https://en.wikipedia.org/wiki/Diet_Coke_and_Mentos_eruption). Both can be great in separation, but together, they are a mess. Libraries like [React](http://facebook.github.io/react) attempt to solve this problem in the view layer by removing asynchrony and direct DOM manipulation. However, React leaves managing the state of your data up to you.
+A lot of this complexity comes from the fact that **we’re mixing two concepts** that are very hard for the human mind to reason about: **mutation and asynchronicity.** I call them [Mentos and Coke](https://en.wikipedia.org/wiki/Diet_Coke_and_Mentos_eruption). Both can be great in separation, but together, they are a mess. Libraries like [React](http://facebook.github.io/react) attempt to solve this problem in the view layer by removing asynchrony and direct DOM manipulation. However, React leaves managing the state of your data up to you.
 
 Following the steps of [Flux](http://facebook.github.io/flux), [CQRS](http://martinfowler.com/bliki/CQRS.html), and [Event Sourcing](http://martinfowler.com/eaaDev/EventSourcing.html), **Redux attempts to make state mutations predictable** by imposing certain restrictions on how and when updates can happen. These restrictions are reflected in the [three principles](ThreePrinciples.md) of Redux.

docs/introduction/ThreePrinciples.md

@@ -6,7 +6,7 @@ Redux can be described in three fundamental principles:
 
 **The [state](../Glossary.md#state) of your whole application is stored in an object tree inside a single [store](../Glossary.md#store).**
 
-This makes it easy to create universal apps. The state from the server can be serialized and hydrated into the client with no extra coding effort. It is easier to debug an application when there is a single state tree. You can also persist your app’s state in development for a faster development cycle. And of course, with a single state tree, you get previously difficult functionality like Undo/Redo for free.
+This makes it easy to create universal apps. The state from the server can be serialized and hydrated into the client with no extra coding effort. It is easier to debug an application when there is a single state tree. You can also persist your app’s state in development for a faster development cycle. And with a single state tree, you get previously difficult functionality like Undo/Redo for free.
 
 ```js
 console.log(store.getState());
@@ -45,7 +45,7 @@ store.dispatch({
 
 **To specify how the state tree is transformed by actions, you write pure [reducers](../Glossary.md#reducer).**
 
-Reducers are just pure functions that take the previous state and an action, and return the next state. You can start with a single reducer, but as your app grows, you can split it into smaller reducers that manage specific parts of the state tree. Because reducers are just functions, you can control the order in which they are called, pass additional data, or even make reusable reducers for common tasks such as pagination.
+Reducers are just pure functions that take the previous state and an action, and return the next state. Remember to return new state objects, instead of mutating the previous state. You can start with a single reducer, but as your app grows, you can split it into smaller reducers that manage specific parts of the state tree. Because reducers are just functions, you can control the order in which they are called, pass additional data, or even make reusable reducers for common tasks such as pagination.
 
 ```js
 function visibilityFilter(state = 'SHOW_ALL', action) {