@vjeux comments

docs/refactor/00-table-of-contents.md

@@ -53,6 +53,13 @@ Working with the browser
 - Component lifecycle
 - Browser support and polyfills
 
+Working with your development and production environments
+- CDN-hosted React
+- Using master
+- In-browser JSX transform
+- Precompiled JSX
+- Helpful open-source projects
+
 Integrating with other UI libraries
 - Using jQuery plugins
 - Letting jQuery manage React components

docs/refactor/01-motivation.md

@@ -17,3 +17,7 @@ React is all about building reusable components. In fact, with React the *only*
 ## Give it five minutes
 
 React challenges a lot of conventional wisdom, and at first glance some of the ideas may seem crazy. We ask that you [give it five minutes](http://37signals.com/svn/posts/3124-give-it-five-minutes) while reading about React; engineers and designers have built thousands of components both inside and outside of Facebook and Instagram, and we hope you'll find it useful!
+
+## Learn more
+
+You can learn more about our motivations behind building React in [this blog post](http://facebook.github.io/react/blog/2013/06/05/why-react.html).

docs/refactor/02-displaying-data.md

@@ -69,6 +69,8 @@ We strongly believe that components are the right way to separate concerns rathe
 
 We've found that the best solution for this problem is to generate markup directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs. In order to make this easier, we've added a *very* simple, **optional** HTML-like syntax for the function calls that generate markup called JSX.
 
-JSX is very small; the example above uses every feature of JSX. To learn more about it, see [JSX in depth](./02.1-jsx-in-depth.md). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
+**JSX lets you write JavaScript function calls with HTML syntax.** To generate, say, a link using pure JavaScript you'd write: `React.DOM.a({href: 'http://facebook.github.io/react/'}, 'Hello React!')`. With JSX this becomes `<a href="http://facebook.github.io/react/">Hello React!</a>`. We've found this has made building React apps easier and designers tend to prefer the syntax, but everyone has their own workflow, so **JSX is not required to use React.**
+
+JSX is very small; the "hello, world" example above uses every feature of JSX. To learn more about it, see [JSX in depth](./02.1-jsx-in-depth.md). Or see the transform in action in [our live JSX compiler](/react/jsx-compiler.html).
 
 The easiest way to get started with JSX is to use the in-browser `JSXTransformer`, but in production you'll want to precompile your code using our command-line [react-tools](http://npmjs.org/package/react-tools) package.

docs/refactor/03-interactivity-and-dynamic-uis.md

@@ -40,7 +40,7 @@ With React you simply pass your event handler as a camelCased prop similar to ho
 
 Under the hood React does a few things to keep your code performant and easy to understand.
 
-**Autobinding.** Every method is automatically bound to its component instance. React caches the bound method such that it's extremely CPU and memory efficient. It's also less typing!
+**Autobinding.** When creating callbacks in JavaScript you usually need to explicitly bind a method to its instance such that the value of `this` is correct. With React, every method is automatically bound to its component instance. React caches the bound method such that it's extremely CPU and memory efficient. It's also less typing!
 
 **Event delegation.** React doesn't actually attach event handlers to the nodes themselves. When React starts up, it starts listening for all events at the top level using a single event listener. When a component is mounted or unmounted, the event handlers are simply added or removed from a fast internal event mapping. When the event occurs, React knows how to dispatch it using this mapping. When there are no event handlers left in the mapping, React's event handlers are simple no-ops. To learn more about why this is fast, see [David Walsh's excellent blog post](http://davidwalsh.name/event-delegate).
 
@@ -52,7 +52,7 @@ In React, you simply update a component's state, and then render a new UI based
 
 ## How state works
 
-A common way to inform React of a data change is by calling `setState(data, callback)`. This method merges `data` into `this.state` and re-renders the component. When the component finishes re-rendering, the optional `callback` is called. Most of the time you'll never need to provide a `callback` since state tends to be so minimal.
+A common way to inform React of a data change is by calling `setState(data, callback)`. This method merges `data` into `this.state` and re-renders the component. When the component finishes re-rendering, the optional `callback` is called. Most of the time you'll never need to provide a `callback` since React will take care of keeping your UI up-to-date for you.
 
 ## What components should have state?
 
@@ -64,11 +64,11 @@ A common pattern is to create several stateless components that just render data
 
 ## What should go in state?
 
-**`this.state` should contain any data that the component's event handlers will change that should trigger a UI update.** In real apps this data tends to be very small and JSON-serializable. When building a stateful component, think about the minimal possible representation of its state, and only store those properties in `this.state`. Inside of `render()` simply compute any other information you need based on this state. You'll find that thinking about and writing applications in this way tends to lead to the most correct application, since adding redundant or computed values to state means that you need to explicitly keep them in sync rather than rely on React computing them for you.
+**`this.state` should contain data that the component's event handlers may change to trigger a UI update.** In real apps this data tends to be very small and JSON-serializable. When building a stateful component, think about the minimal possible representation of its state, and only store those properties in `this.state`. Inside of `render()` simply compute any other information you need based on this state. You'll find that thinking about and writing applications in this way tends to lead to the most correct application, since adding redundant or computed values to state means that you need to explicitly keep them in sync rather than rely on React computing them for you.
 
 ## What *shouldn't* go in state?
 
-**`this.state`** should contain the minimal amount of data needed to represent your UI's state. As such, it should not contain:
+**`this.state`** should only contain the minimal amount of data needed to represent your UI's state. As such, it should not contain:
-* **Computed data.** Don't worry about precomputing values based on state -- it's easier to ensure that your UI is consistent if you do all computation within `render()`
+* **Computed data.** Don't worry about precomputing values based on state -- it's easier to ensure that your UI is consistent if you do all computation within `render()`. For example, if you have an array of list items in state and you want to render the count as a string, simply render `this.state.listItems.length + ' list items'` in your `render()` method rather than storing it on state.
-* **React component nodes.** Build them in `render()` based on underlying props and state.
+* **React components.** Build them in `render()` based on underlying props and state.
 * **Duplicated data from props.** Try to use props as the source of truth where possible. Because props can change over time, it's appropriate to store props in state to be able to know its previous values.

docs/refactor/07-working-with-the-browser.md

@@ -1,6 +1,6 @@
 # Working with the browser
 
-React provides powerful abstractions that free you from touching the DOM directly in most cases, but sometimes you simply need to access the underlying API, perhaps to work with a third-party library.
+React provides powerful abstractions that free you from touching the DOM directly in most cases, but sometimes you simply need to access the underlying API, perhaps to work with a third-party library or existing code.
 
 ## The mock DOM