diff --git a/content/tutorial/nav.yml b/content/tutorial/nav.yml
index adc5cf3a7..a679ee9d0 100644
--- a/content/tutorial/nav.yml
+++ b/content/tutorial/nav.yml
@@ -1,21 +1,30 @@
- title: Tutorial
items:
- - id: before-we-start
- title: Before We Start
- href: /tutorial/tutorial.html#before-we-start
+ - id: before-we-start-the-tutorial
+ title: Before We Start the Tutorial
+ href: /tutorial/tutorial.html#before-we-start-the-tutorial
forceInternal: true
subitems:
- id: what-were-building
- title: What We're Building
- href: /tutorial/tutorial.html#what-were-building
+ title: What Are We Building?
+ href: /tutorial/tutorial.html#what-are-we-building
forceInternal: true
- id: prerequisites
title: Prerequisites
href: /tutorial/tutorial.html#prerequisites
forceInternal: true
- - id: how-to-follow-along
- title: How to Follow Along
- href: /tutorial/tutorial.html#how-to-follow-along
+ - id: setup-for-the-tutorial
+ title: Setup for the Tutorial
+ href: /tutorial/tutorial.html#setup-for-the-tutorial
+ forceInternal: true
+ subitems:
+ - id: setup-option-1-write-code-in-the-browser
+ title: "Option 1: Write Code in the Browser"
+ href: /tutorial/tutorial.html#setup-option-1-write-code-in-the-browser
+ forceInternal: true
+ - id: setup-option-2-local-development-environment
+ title: "Option 2: Local Development Environment"
+ href: /tutorial/tutorial.html#setup-option-2-local-development-environment
forceInternal: true
- id: help-im-stuck
title: Help, I'm Stuck!
@@ -27,30 +36,34 @@
forceInternal: true
subitems:
- id: what-is-react
- title: What is React?
+ title: What Is React?
href: /tutorial/tutorial.html#what-is-react
forceInternal: true
- - id: getting-started
- title: Getting Started
- href: /tutorial/tutorial.html#getting-started
+ - id: inspecting-the-starter-code
+ title: Inspecting the Starter Code
+ href: /tutorial/tutorial.html#inspecting-the-starter-code
forceInternal: true
- id: passing-data-through-props
title: Passing Data Through Props
href: /tutorial/tutorial.html#passing-data-through-props
forceInternal: true
- - id: an-interactive-component
- title: An Interactive Component
- href: /tutorial/tutorial.html#an-interactive-component
+ - id: making-an-interactive-component
+ title: Making an Interactive Component
+ href: /tutorial/tutorial.html#making-an-interactive-component
forceInternal: true
- id: developer-tools
title: Developer Tools
href: /tutorial/tutorial.html#developer-tools
forceInternal: true
- - id: lifting-state-up
- title: Lifting State Up
- href: /tutorial/tutorial.html#lifting-state-up
+ - id: completing-the-game
+ title: Completing the Game
+ href: /tutorial/tutorial.html#completing-the-game
forceInternal: true
subitems:
+ - id: lifting-state-up
+ title: Lifting State Up
+ href: /tutorial/tutorial.html#lifting-state-up
+ forceInternal: true
- id: why-immutability-is-important
title: Why Immutability Is Important
href: /tutorial/tutorial.html#why-immutability-is-important
@@ -67,18 +80,26 @@
title: Declaring a Winner
href: /tutorial/tutorial.html#declaring-a-winner
forceInternal: true
- - id: storing-a-history
- title: Storing A History
- href: /tutorial/tutorial.html#storing-a-history
+ - id: adding-time-travel
+ title: Adding Time Travel
+ href: /tutorial/tutorial.html#adding-time-travel
forceInternal: true
subitems:
- - id: showing-the-moves
- title: Showing the Moves
- href: /tutorial/tutorial.html#showing-the-moves
+ - id: storing-a-history-of-moves
+ title: Storing a History of Moves
+ href: /tutorial/tutorial.html#storing-a-history-of-moves
forceInternal: true
- - id: keys
- title: Keys
- href: /tutorial/tutorial.html#keys
+ - id: lifting-state-up-again
+ title: Lifting State Up, Again
+ href: /tutorial/tutorial.html#lifting-state-up-again
+ forceInternal: true
+ - id: showing-the-past-moves
+ title: Showing the Past Moves
+ href: /tutorial/tutorial.html#showing-the-past-moves
+ forceInternal: true
+ - id: picking-a-key
+ title: Picking a Key
+ href: /tutorial/tutorial.html#picking-a-key
forceInternal: true
- id: implementing-time-travel
title: Implementing Time Travel
diff --git a/content/tutorial/tutorial.md b/content/tutorial/tutorial.md
index 63ecdf364..ebe79590d 100644
--- a/content/tutorial/tutorial.md
+++ b/content/tutorial/tutorial.md
@@ -12,45 +12,41 @@ redirect_from:
- "docs/tutorial-zh-CN.html"
---
-## Before We Start
+## Before We Start the Tutorial
-### What We're Building
+### What Are We Building?
-Today, we're going to build an interactive tic-tac-toe game.
+In this tutorial, we'll show how to build an interactive tic-tac-toe game with React.
-If you like, you can check out the final result here: [Final Result](https://codepen.io/gaearon/pen/gWWZgR?editors=0010). Don't worry if the code doesn't make sense to you yet, or if it uses an unfamiliar syntax. We will be learning how to build this game step by step throughout this tutorial.
+You can see what we'll be building here: [Final Result](https://codepen.io/gaearon/pen/gWWZgR?editors=0010). If the code doesn't make sense to you, or if you are unfamiliar with the code's syntax, don't worry! The goal of this tutorial is to help you understand React and its syntax.
-Try playing the game. You can also click on a button in the move list to go "back in time" and see what the board looked like just after that move was made.
+We recommend that you check out the tic-tac-toe game before continuing with the tutorial. One of the features that you'll notice is that there is a numbered list to the right of the game's board. This list gives you a history of all of the moves that have occurred in the game, and is updated as the game progresses.
-Once you get a little familiar with the game, feel free to close that tab, as we'll start from a simpler template in the next sections.
+You can close the tic-tac-toe game once you're familiar with it. We'll be starting from a simpler template in this tutorial. Our next step is to set you up so that you can start building the game.
### Prerequisites
-We'll assume some familiarity with HTML and JavaScript, but you should be able to follow along even if you haven't used them before.
+We'll assume that you have some familiarity with HTML and JavaScript, but you should be able to follow along even if you're coming from a different programming language. We'll also assume that you're familiar with programming concepts like functions, objects, arrays, and to a lesser extent, classes.
-If you need a refresher on JavaScript, we recommend reading [this guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript). Note that we're also using some features from ES6, a recent version of JavaScript. In this tutorial, we're using [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), [classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), [`let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let), and [`const`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) statements. You can use the [Babel REPL](babel://es5-syntax-example) to check what ES6 code compiles to.
+If you need to review JavaScript, we recommend reading [this guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript). Note that we're also using some features from ES6 -- a recent version of JavaScript. In this tutorial, we're using [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), [classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes), [`let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let), and [`const`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) statements. You can use the [Babel REPL](babel://es5-syntax-example) to check what ES6 code compiles to.
-### How to Follow Along
+## Setup for the Tutorial
-There are two ways to complete this tutorial: you could either write the code right in the browser, or you could set up a local development environment on your machine. You can choose either option depending on what you feel comfortable with.
+There are two ways to complete this tutorial: you can either write the code in your browser, or you can set up a local development environment on your computer.
-#### If You Prefer to Write Code in the Browser
+### Setup Option 1: Write Code in the Browser
This is the quickest way to get started!
-First, open this [starter code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010) in a new tab. It should display an empty tic-tac-toe field. We will be editing that code during this tutorial.
+First, open this [starter code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010) in a new tab. The new tab should display an empty tic-tac-toe game board and React code. We will be editing the React code in this tutorial.
-You can now skip the next section about setting up a local development environment and head straight to the [overview](#overview).
+You can now skip the second setup option, and go to the [Overview](#overview) section to get an overview of React.
-#### If You Prefer to Write Code in Your Editor
+### Setup Option 2: Local Development Environment
-Alternatively, you can set up a project on your computer.
+**This is completely optional and not required for this tutorial!**
-Note: **this is completely optional and not required for this tutorial!**
-
-This is more work, but lets you work from the comfort of your editor.
-
-If you want to do it, here are the steps to follow:
+This setup requires more work but allows you to complete the tutorial using an editor of your choice. Here are the steps to follow:
1. Make sure you have a recent version of [Node.js](https://nodejs.org/en/) installed.
2. Follow the [installation instructions](/docs/add-react-to-a-new-app.html) to create a new project.
@@ -85,15 +81,15 @@ We recommend following [these instructions](http://babeljs.io/docs/editors) to c
### Help, I'm Stuck!
-If you get stuck, check out the [community support resources](/community/support.html). In particular, [Reactiflux chat](/community/support.html#reactiflux-chat) is a great way to get quick help. If you don't get a good answer anywhere, please file an issue, and we'll help you out.
-
-With this out of the way, let's get started!
+If you get stuck, check out the [community support resources](/community/support.html). In particular, [Reactiflux Chat](/community/support.html#reactiflux-chat) is a great way to get help quickly. If you don't receive an answer, or if you remain stuck, please file an issue, and we'll help you out.
## Overview
-### What is React?
+Now that you're set up, let's get an overview of React!
-React is a declarative, efficient, and flexible JavaScript library for building user interfaces.
+### What Is React?
+
+React is a declarative, efficient, and flexible JavaScript library for building user interfaces. It lets you compose complex UIs from small and isolated pieces of code called "components".
React has a few different kinds of components, but we'll start with `React.Component` subclasses:
@@ -116,11 +112,11 @@ class ShoppingList extends React.Component {
// Example usage:
```
-We'll get to the funny XML-like tags in a second. Your components tell React what you want to render – then React will efficiently update and render just the right components when your data changes.
+We'll get to the funny XML-like tags soon. We use components to tell React what we want to see on the screen. When our data changes, React will efficiently update and re-render our components.
-Here, ShoppingList is a **React component class**, or **React component type**. A component takes in parameters, called `props`, and returns a hierarchy of views to display via the `render` method.
+Here, ShoppingList is a **React component class**, or **React component type**. A component takes in parameters, called `props` (short for "properties"), and returns a hierarchy of views to display via the `render` method.
-The `render` method returns a *description* of what you want to render, and then React takes that description and renders it to the screen. In particular, `render` returns a **React element**, which is a lightweight description of what to render. Most React developers use a special syntax called JSX which makes it easier to write these structures. The `
` syntax is transformed at build time to `React.createElement('div')`. The example above is equivalent to:
+The `render` method returns a *description* of what you want to see on the screen. React takes the description and displays the result. In particular, `render` returns a **React element**, which is a lightweight description of what to render. Most React developers use a special syntax called "JSX" which makes these structures easier to write. The `` syntax is transformed at build time to `React.createElement('div')`. The example above is equivalent to:
```javascript
return React.createElement('div', {className: 'shopping-list'},
@@ -131,31 +127,33 @@ return React.createElement('div', {className: 'shopping-list'},
[See full expanded version.](babel://tutorial-expanded-version)
-If you're curious, `createElement()` is described in more detail in the [API reference](/docs/react-api.html#createelement), but we won't be using it directly in this tutorial. Instead, we will keep using JSX.
+If you're curious, `createElement()` is described in more detail in the [API reference](/docs/react-api.html#createelement), but we won't be using it in this tutorial. Instead, we will keep using JSX.
-You can put any JavaScript expression within braces inside JSX. Each React element is a real JavaScript object that you can store in a variable or pass around your program.
+JSX comes with the full power of JavaScript. You can put *any* JavaScript expressions within braces inside JSX. Each React element is a JavaScript object that you can store in a variable or pass around in your program.
-The `ShoppingList` component only renders built-in DOM components, but you can compose custom React components just as easily, by writing ``. Each component is encapsulated so it can operate independently, which allows you to build complex UIs out of simple components.
+The `ShoppingList` component above only renders built-in DOM components like `` and ``. But you can compose and render custom React components too. For example, we can now refer to the whole shopping list by writing ``. Each React component is encapsulated and can operate independently; this allows you to build complex UIs from simple components.
-### Getting Started
+## Inspecting the Starter Code
-Start with this example: [Starter Code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010).
+**If you're going to work on the tutorial in your browser,** open this code in a new tab: [Starter Code](https://codepen.io/gaearon/pen/oWWQNa?editors=0010).
-It contains the shell of what we're building today. We've provided the styles so you only need to worry about the JavaScript.
+**If you're going to work on the tutorial locally,** open `src/index.js` in your project folder (you have already touched this file during the [setup](#setup-option-2-local-development-environment)).
-In particular, we have three components:
+This Starter Code is the base of what we're building. We've provided the CSS styling so that you only need focus on learning React and programming the tic-tac-toe game.
+
+By inspecting the code, you'll notice that we have three React components:
* Square
* Board
* Game
-The Square component renders a single `