Docs updates per community response

docs/_js/examples/timer.js

@@ -3,7 +3,6 @@
  */
 
 var TIMER_COMPONENT = "\
-/** @jsx React.DOM */\n\
 var Timer = React.createClass({\n\
   getInitialState: function() {\n\
     return {secondsElapsed: 0};\n\
@@ -15,15 +14,13 @@ var Timer = React.createClass({\n\
     setInterval(this.tick, 1000);\n\
   },\n\
   render: function() {\n\
-    return (\n\
-      <div>\n\
-        {'Seconds Elapsed: ' + this.state.secondsElapsed}\n\
-      </div>\n\
+    return React.DOM.div({},\n\
+      'Seconds Elapsed: ' + this.state.secondsElapsed\n\
     );\n\
   }\n\
 });\n\
 \n\
-React.renderComponent(<Timer />, mountNode);\
+React.renderComponent(Timer({}), mountNode);\
 ";
 
 React.renderComponent(

docs/docs/common-questions.md

@@ -5,6 +5,7 @@ layout: docs
 prev: tutorial.html
 next: syntax.html
 ---
+
 ### What browsers does React support?
 
 React supports the latest two Chrome, Firefox, Safari, and Internet Explorer versions. React can work with Internet Explorer 8 with polyfills.
@@ -17,6 +18,11 @@ React requires ES5 JavaScript shims to run in Internet Explorer 8. Include the [
 
 The [Instagram](http://instagram.com/) website is built entirely in React. The [Facebook](https://www.facebook.com/) website is also increasingly using React, including the common commenting plugin across the site.
 
+### I don't get it. React is confusing!
+
+[This blog post by a member of the React team](http://www.quora.com/Pete-Hunt/Posts/React-Under-the-Hood) talks about some of the reasons
+why React is designed the way that it is.
+
 ### Can I integrate with other JavaScript libraries?
 
 Absolutely! In fact, we encourage it! See [our GitHub repo](http://github.com/facebook/react/) for a [TodoMVC example using Backbone](https://github.com/facebook/react/tree/master/examples/todomvc-backbone) and a [jQuery + Bootstrap modal demo](https://github.com/facebook/react/tree/master/examples/jquery-bootstrap).

docs/docs/syntax.md

@@ -13,6 +13,22 @@ with React.
 JSX makes code that deeply nests React components more readable, and writing it
 feels like writing HTML. React documentation examples make use of JSX.
 
+## Why JSX? It seems like a terrible idea.
+
+First of all, **don't use JSX if you don't like it!** All of React's features
+work just fine without using JSX. Simply construct your markup using the functions
+on `React.DOM`. For example, here's how to construct a simple link:
+
+```javascript
+var mylink = React.DOM.a({href: 'http://facebook.github.io/react'}, 'Hello React');
+```
+
+However, we like JSX for a bunch of reasons:
+
+- It's easier to visualize the structure of the DOM
+- Designers are more comfortable making changes
+- It's familiar for those who have used MXML or XAML
+
 ## The Transform
 
 JSX transforms XML-like syntax into native JavaScript. It turns XML elements and

docs/index.md

@@ -6,17 +6,16 @@ id: home
 <section class="light home-section">
   <div class="marketing-row">
     <div class="marketing-col">
-      <h3>Declarative</h3>
+      <h3>The &quot;V&quot; in MVC</h3>
       <p>
-        React uses a declarative paradigm that makes it easier to reason about
-        your application.
+        Write reusable UI components in JavaScript. Read and write to any data source.
       </p>
     </div>
     <div class="marketing-col">
-      <h3>Efficient</h3>
+      <h3>Fast &amp; Declarative</h3>
       <p>
-        React minimizes interactions with the DOM by using a mock representation
-        of the DOM.
+        Describe how you want your component to look. React will automatically compute
+        the fastest way to keep the UI up-to-date when the data changes.
       </p>
     </div>
     <div class="marketing-col">
@@ -35,7 +34,8 @@ id: home
       <p>
         React components implement a `render()` method that takes input data and
         returns what to display. This example constructs the component using an
-        XML-like syntax called JSX. Input data is passed to the component as XML
+        XML-like syntax called JSX, but <strong>JSX is optional; you don&apos;t
+        need to use it</strong>. Input data is passed to the component as XML
         attributes, and `render()` accesses this data via `this.props`.
       </p>
       <div id="helloExample"></div>
@@ -46,7 +46,8 @@ id: home
         In addition to taking data from its creator (accessed via `this.props`),
         a component can maintain internal state data (accessed via
         `this.state`). When a component's state data changes, the rendered
-        markup will be updated by re-invoking `render()`.
+        markup will be updated by re-invoking `render()`. <strong>This example
+        doesn&apos;t use JSX</strong>, but you could if you wanted to.
       </p>
       <div id="timerExample"></div>
     </div>