Tutorial document tweak #1025

cyan33 · 2018-06-30T20:54:58Z

Tweaked a little bit about our newly-written get-started section and tutorial.

Open to any re-wording suggestions. And I'll comment in the file change, that why I personally think it would be better written this way.

cc @gaearon @bvaughn

cyan33 · 2018-06-30T20:56:19Z

content/docs/getting-started.md


 If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so we'd only recommend using this for simple demos.

-### Add React to a Website
+### Through the `<script>` Tag


Add React to a Website doesn't tell me the real thing that we want to address in this section. We want to tell people all you need is a script tag.

I see what you want to do but I'm not sure "Through the <script> Tag" works as a title. Would you also put it in navbar and on the page itself? Or keep headers inconsistent?

I'm not sure "through the script tag" also necessarily implies that you don't need to configure anything.

cyan33 · 2018-06-30T20:56:56Z

content/docs/getting-started.md


 ### Create a New React App

-When starting a React project, [a simple HTML page with script tags](/docs/add-react-to-a-website.html) might still be the best option. It only takes a minute to set up!


This seems to me a little bit redundant, as we have already talked about this in the previous section.

cyan33 · 2018-06-30T20:57:51Z

content/docs/getting-started.md

@@ -77,7 +75,7 @@ We recommend going through [this JavaScript overview](https://developer.mozilla.

 If you prefer to **learn by doing,** check out our [practical tutorial](/tutorial/tutorial.html). In this tutorial, we build a tic-tac-toe game in React. You might be tempted to skip it because you're not building games -- but give it a chance. The techniques you'll learn in the tutorial are fundamental to building *any* React apps, and mastering it will give you a much deeper understanding.

-### Step-by-Step Guide
+### Conceptual Step-by-Step Guide


Step-by-Step is vague. If it's a conceptual guide, I think it'd be better we explicitly tell people that.

reactjs-bot · 2018-06-30T20:57:59Z

Deploy preview for reactjs ready!

Built with commit 1d6f655

https://deploy-preview-1025--reactjs.netlify.com

cyan33 · 2018-06-30T20:59:02Z

content/tutorial/tutorial.md

@@ -162,7 +162,7 @@ The `ShoppingList` component above only renders built-in DOM components like `<d

 ## Inspecting the Starter Code

-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)**. If you're going to work on the tutorial **locally,** instead open `src/index.js` in your project folder (you have already touched this file during the [setup](#setup-option-2-local-development-environment)).
+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)**. If you're going to work on the tutorial **locally,** open `src/index.js` in your project folder instead (you have already touched this file during the [setup](#setup-option-2-local-development-environment)).


I moved instead to the end of the sentence because I got easily mistaken with instead of and instead. It makes me feel like we are not doing this, which is "instead of".

cyan33 · 2018-06-30T20:59:36Z

content/tutorial/tutorial.md

@@ -321,7 +321,7 @@ The React Devtools extension for [Chrome](https://chrome.google.com/webstore/det

 <img src="../images/tutorial/devtools.png" alt="React Devtools" style="max-width: 100%">

-The React DevTools let you check the props and the state of your React components.
+Moreover, the React DevTools let you check the props and the state of your React components, which makes it easier to debug the data flow and keep track of how they change in your application.


Let's tell people what's good about this as well.

cyan33 · 2018-06-30T21:00:31Z

content/tutorial/tutorial.md

@@ -332,6 +332,15 @@ After installing React DevTools, you can right-click on any element on the page,
 3. Click "Change View" and then choose "Debug mode".
 4. In the new tab that opens, the devtools should now have a React tab.

+### A Quick Summary Before Moving On


I always like a quick summary in between sections. For one thing, it gives me a pause to reflect on what I've learned. Also, it addresses the core things that I need to be aware of.

cyan33 · 2018-06-30T21:01:52Z

content/tutorial/tutorial.md

@@ -340,7 +349,7 @@ We now have the basic building blocks for our tic-tac-toe game. To have a comple

 Currently, each Square component maintains the game's state. To check for a winner, we'll maintain the value of each of the 9 squares in one location.

-We may think that Board should just ask each Square for the Square's state. Although this approach is possible in React, we discourage it because the code becomes difficult to understand, susceptible to bugs, and hard to refactor. Instead, the best approach is to store the game's state in the parent Board component instead of in each Square. The Board component can tell each Square what to display by passing a prop, [just like we did when we passed a number to each Square](#passing-data-through-props).
+We may think that Board should just ask each Square for the Square's own state. Although this approach is possible in React, we discourage it because it conflicts with the **uni-directional data flow (top-down)** convention of React, which makes the code becomes difficult to understand, susceptible to bugs, and hard to refactor. Instead, the best approach is to store the game's state in the parent Board component instead of in each Square. The Board component can tell each Square what to display by passing a prop, [just like we did when we passed a number to each Square](#passing-data-through-props).


we discourage it because the code becomes difficult to understand, susceptible to bugs, and hard to refactor.

That doesn't seem to me a good reason. I know it's hard to make people understand why we should "lifting state up". But this is slightly better I think.

cyan33 · 2018-06-30T21:02:17Z

content/tutorial/tutorial.md

@@ -535,7 +544,7 @@ Note how in `handleClick`, we call `.slice()` to create a copy of the `squares`

 ### Why Immutability Is Important

-In the previous code example, we suggested that you use the `.slice()` operator to create a copy of the `squares` array to modify instead of modifying the existing array. We'll now discuss immutability and why immutability is important to learn.
+[An immutable object](https://en.wikipedia.org/wiki/Immutable_object) is an object whose state cannot be **modified** after it is created. In the previous code example, we suggested that you use the `.slice()` operator to **create a copy of the `squares` array to modify instead of modifying the existing array**. We'll now discuss immutability and why immutability is important to learn.


Add a little background of immutability before we dive in.

cyan33 · 2018-06-30T21:03:28Z

content/tutorial/tutorial.md

@@ -579,7 +588,7 @@ You can learn more about `shouldComponentUpdate()` and how you can build *pure c

 We'll now change the Square to be a **functional component**.

-In React, **functional components** are a simpler way to write components that only contain a `render` method and don't have their own state. Instead of defining a class which extends `React.Component`, we can write a function that takes `props` as input and returns what should be rendered. Functional components are less tedious to write than classes, and many components can be expressed this way.
+We've covered how we create a React component by creating a class that extends `React.Component`. Other than that, **functional components** are a simpler way to write components that only contain a `render` method and don't have their own state. Instead of defining a class which extends `React.Component`, we can write a function that takes `props` as input and returns what should be rendered. Functional components are less tedious to write than classes, and many components can be expressed this way.


It might not be intuitive to connect functional components and class components for a beginner. So we might as well need to recap a bit here to let people know this is an alternative.

cyan33 · 2018-06-30T21:04:29Z

content/tutorial/tutorial.md

@@ -1090,7 +1099,8 @@ When a list is re-rendered, React takes each list item's key and searches the pr

 **It's strongly recommended that you assign proper keys whenever you build dynamic lists.** If you don't have an appropriate key, you may want to consider restructuring your data so that you do.

-If no key is specified, React will present a warning and use the array index as a key by default. Using the array index as a key is problematic when trying to re-order a list's items or inserting/removing list items. Explicitly passing `key={i}` silences the warning but has the same problems as array indices and is not recommended in most cases.
+> Warning:
+> If no key is specified, React will present a warning and use the array index as a key by default. Using the array index as a key is problematic when trying to re-order a list's items or inserting/removing list items. Explicitly passing `key={i}` silences the warning but has the same problems as array indices and is not recommended in most cases.


This is a bad practice that even myself have been following along for a long time. Better make it more alarming.

cyan33 · 2018-06-30T21:04:52Z

content/tutorial/tutorial.md

@@ -1215,4 +1225,8 @@ If you have extra time or want to practice your new React skills, here are some
 5. When someone wins, highlight the three squares that caused the win.
 6. When no one wins, display a message about the result being a draw.

-Throughout this tutorial, we touched on React concepts including elements, components, props, and state. For a more detailed explanation of each of these topics, check out [the rest of the documentation](/docs/hello-world.html). To learn more about defining components, check out the [`React.Component` API reference](/docs/react-component.html).
+Throughout this tutorial, we touched on React concepts including elements, components, props, and state.


Separate this single sentence in three paragraphs to make it look better :)

gaearon · 2018-07-04T11:45:01Z

content/docs/getting-started.md

@@ -36,18 +36,16 @@ React has been designed from the start for gradual adoption, and **you can use a

 ### Online Playgrounds

-If you're interested in playing around with React, you can use an online code playground. Try a Hello World template on [CodePen](codepen://hello-world) or [CodeSandbox](https://codesandbox.io/s/new).
+To start playing with React instantly, you can use an online code playground, without having to bother configuration and environment setup. Try a Hello World template on [CodePen](codepen://hello-world) or [CodeSandbox](https://codesandbox.io/s/new).


Missing "with" after "bother"?

That said I don't think we should give people the idea about React needing configuration or environment setup. Let's not forget new readers aren't necessarily expecting this either.

gaearon · 2018-07-04T11:49:57Z

content/docs/getting-started.md


 If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so we'd only recommend using this for simple demos.

-### Add React to a Website
+### Through the `<script>` Tag


I see what you want to do but I'm not sure "Through the <script> Tag" works as a title. Would you also put it in navbar and on the page itself? Or keep headers inconsistent?

I'm not sure "through the script tag" also necessarily implies that you don't need to configure anything.

cyan33 · 2018-07-05T06:28:25Z

@gaearon I've reverted some of the changes that is improper or need further discussion. See if the rest of the tweak looks good to you. 😄

Thanks for your time to review!

facebook-github-bot added the CLA Signed label Jun 30, 2018

cyan33 commented Jun 30, 2018

View reviewed changes

gaearon reviewed Jul 4, 2018

View reviewed changes

tutorial document tweak

1d6f655

cyan33 force-pushed the tutorial-doc-tweak branch from 7621901 to 1d6f655 Compare July 5, 2018 06:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tutorial document tweak #1025

Tutorial document tweak #1025

cyan33 commented Jun 30, 2018 •

edited

Loading

cyan33 Jun 30, 2018

gaearon Jul 4, 2018

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

reactjs-bot commented Jun 30, 2018 •

edited

Loading

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

cyan33 Jun 30, 2018

gaearon Jul 4, 2018

gaearon Jul 4, 2018

cyan33 commented Jul 5, 2018 •

edited

Loading


		### Create a New React App

		When starting a React project, [a simple HTML page with script tags](/docs/add-react-to-a-website.html) might still be the best option. It only takes a minute to set up!

Tutorial document tweak #1025

Are you sure you want to change the base?

Tutorial document tweak #1025

Conversation

cyan33 commented Jun 30, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

reactjs-bot commented Jun 30, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cyan33 commented Jul 5, 2018 • edited Loading

cyan33 commented Jun 30, 2018 •

edited

Loading

reactjs-bot commented Jun 30, 2018 •

edited

Loading

cyan33 commented Jul 5, 2018 •

edited

Loading