[Tutorial] Make it easier to follow the instructions #9454

brigand · 2017-04-18T20:42:53Z

It's just a few extra lines of code to show the full Square component so I've included it here.

Also added a note about passing a function vs calling a function. This comes up a lot on IRC; especially with people coming from angular, or with less experience with functions as values

gaearon

What about adding "context" with class or function declaration to all other places? So that it's more obvious where we are changing.

brigand · 2017-04-19T00:44:15Z

@gaearon am I on the right track?

brigand · 2017-04-19T01:22:10Z

I think this is ready for review.

gaearon · 2017-04-19T10:51:52Z

docs/tutorial/tutorial.md

 class Square extends React.Component {
  constructor() {
    super();
    this.state = {
      value: null,
    };
  }
-  // ...
+  render() {
+    // same as above


Maybe just copy and paste it here? With highlighting it's not really that distracting, and it helps to stay in the flow.

gaearon · 2017-04-19T10:54:19Z

This is a good start. Do you want to take a pass at the whole tutorial and do the same thing anywhere there is not quite enough context? For example I’m thinking of later Board code.

I’m not sure if it’s better to copy and paste or leave a comment like “// same as before”—I’d leave this to your discretion (whatever is easier to follow in every particular case).

brigand · 2017-04-19T19:59:34Z

docs/tutorial/tutorial.md

@@ -132,7 +132,7 @@ After: You should see a number in each square in the rendered output.

 ### An Interactive Component

-Let's make the Square component fill in an "X" when you click it. Try changing the button tag returned in the `render()` function of the `Square` like this:


There was inconsistent use of backticks in component names. Removing them reduces some noise.

brigand · 2017-04-19T20:01:20Z

docs/tutorial/tutorial.md

+      <div>
+        <div className="status">{status}</div>
+        <div className="board-row">
+          {this.renderSquare(0)}{this.renderSquare(1)}{this.renderSquare(2)}


Just saving some vertical space by putting these on one line.

brigand · 2017-04-20T00:22:44Z

I think that in the cases where we're replacing a previously defined method, we don't need to show the full class. Happy to change that if you disagree.

Edit: specifically talking about Board and Game which get quite large.

gaearon · 2017-04-20T10:54:03Z

docs/tutorial/tutorial.md

@@ -200,6 +226,10 @@ class Board extends React.Component {
      squares: Array(9).fill(null),
    };
  }
+  render() {
+    // TODO


This is not what I see when I follow along from the starter CodePen. Can we either make it similar or make it clear the code is just being skipped?

brigand · 2017-04-24T22:48:15Z

Added some codepen links. Ref: #9510

cc @gaearon

gaearon

This looks great. Let’s just make sure all CodePens are working. It would help if you could do a complete read-through and check for mistakes.

gaearon · 2017-04-26T11:17:33Z

docs/tutorial/tutorial.md

 ```

 Whenever `this.setState` is called, an update to the component is scheduled, causing React to merge in the passed state update and rerender the component along with its descendants. When the component rerenders, `this.state.value` will be `'X'` so you'll see an X in the grid.

 If you click on any square, an X should show up in it.

+<a href="https://codepen.io/brigand/pen/XRjPRg?editors=0010" target="_blank">View the current code</a>.


"If you click on any square, an X should show up in it."

I don't think the linked CodePen does this. I see an alert in it.

gaearon · 2017-04-26T11:18:16Z

docs/tutorial/tutorial.md

+      <div>
+        <div className="status">{status}</div>
+        <div className="board-row">
+          {this.renderSquare(0)}{this.renderSquare(1)}{this.renderSquare(2)}


I’m okay with this, but please change the existing “final” CodePen linked from intro paragraphs to match the new style. They should all be consistent with the doc.

Also I think this might give people the wrong impression that JSX requires you put things on a single line or they’ll be split by newlines. This is not true. So maybe wordier version is clearer in this case.

Fixed, went with the multiple lines. I'll update the codepens next.

gaearon · 2017-04-26T11:22:52Z

docs/tutorial/tutorial.md

@@ -315,19 +426,21 @@ function Square(props) {

 You'll need to change `this.props` to `props` both times it appears. Many components in your apps will be able to be written as functional components: these components tend to be easier to write and React will optimize them more in the future.

+<a href="https://codepen.io/brigand/pen/OmRoGV?editors=0010" target="_blank">View the current code</a>.


This CodePen doesn’t work for me.

brigand · 2017-04-27T01:58:38Z

Not ready for review yet.

gaearon · 2017-04-27T11:51:47Z

Thanks.

Yesterday I went through the tutorial (in its current form) with two people learning React, and got a lot of feedback. I will summarize it here. I would appreciate if you could dedicate some time to fixing these issues, as they are related to the work you’re doing (in fact you may already have solved some of them).

It is not obvious the "following along locally" section can be skipped. The rest of the tutorial is linear, so some people assume they have to install Node and stuff. Possible solution: include a disclaimer like "You can skip this section if you don't want to install anything on your machine, and prefer to learn in the browser."
The tutorial says to replace this.props.value with this.state.value. But this.props.value isn't there if you follow it, because it has been replaced with {/* TODO */} in the previous snippet when we added an alert. Possible solution: leave this.props.value there when we tell to add an alert.
When following along locally, CRA complains calculateWinner is unused. While this is just a warning, people think it might mean something is wrong. We should probably remove it from the initial code completely, and instead tell people to copy and paste it from the tutorial code when they get to the relevant section.
There are a few places where it's not obvious which parts of the code are being replaced, or where to paste new pieces of code. For example some people don't know ES6 class syntax enough to know what adding a method looks like. The section on adding constructor can be misinterpreted as replacing all class code with constructor alone. Similarly, the section on replacing class with a function doesn't make it clear enough that the entire class definition needs to be replaced. Possible solution: always show context, and if we must rely on // ..., replace this with a more descriptive placeholder.
On a related node, a lot of people learn by copy pasting things until they work (and later studying what they did in more detail). We can't really forbid them from doing so, and we should embrace that people will do this, and make the experience better for them. One detail that caught my eye is we sometimes unindent event handlers for clarity. But as a consequence they appear with wrong indentation when pasted into CodePen. For people not very familiar with ES6 classes and JSX, it hinders understanding of the code structure, and we should make sure just following instructions and copy pasting snippets usually gives you the right result. You should know what to copy paste where, and the result should be indented correctly if you followed the instructions.
There are sentences like Now change the render method which don't mention which render method to change. It is very easy to get lost in the beginning between Board and Square.
The CodePen Debug view is not enabled until you press "Fork". Even if you're logged in, you won’t see it unless you own the pen.

I’m sorry this is a lot of stuff, but I believe we can only address this in a batch with somebody who feels ownership over this. I’m very pleased with how you handle those issues so far so I think you’re the best person to address this comprehensively.

Thanks!

brigand · 2017-04-28T03:09:50Z

docs/tutorial/tutorial.md

@@ -34,7 +34,7 @@ We'll be using an online editor called CodePen in this guide. You can begin by o

 #### Following Along Locally

-You can also follow along locally if you don't mind a few extra steps:
+Alternatively, you can set up a project on your computer. This is more work, but gives you a standard development environment, including support for <a href="https://medium.freecodecamp.com/javascript-modules-a-beginner-s-guide-783f7d7a5fcc" target="_blank">modules</a>.


I put a lot of thought into this piece, but I don't think it's quite right. My thoughts:

I think "alternatively" is a clear enough indicator that this isn't required.

"standard development environment" is presumptuous, but I think it's important to emphasize that this reflects the way React apps are developed.

Understanding modules is an important part of normal React app development, but maybe we shouldn't send readers off in that direction at this point.

brigand · 2017-04-28T03:11:48Z

I'm going to keep working on this. Sorry for not reviewing my work thoroughly last time.

I'll address the new issues over the next few days.

brigand · 2017-04-30T02:51:20Z

@gaearon ready for review.

gaearon · 2017-05-01T16:22:04Z

I made some more changes related to fixing accidentally missing pieces, rewording "replace X with Y" instructions to be clearer, and removing the inconsistent anchor tags (let's just use Markdown links everywhere).

gaearon · 2017-05-01T16:22:35Z

I am merging this but I'd appreciate another proof read now.

* tutorial: adds note about onClick * tutorial: show full square component * merge * fixes line number * tutorial: misc changes * fixes Board render initial code sample * [tutorial] adds codepen links and misc small fixes * removes useless arrow functions, #9531 * {this.renderSquare} new lines * be more explicit about history state * fixes highlight * following along locally * changes todo to this.props.value * removes calculateWinner from initial codepens and includes it in tutorial * removes note about calculateWinner at end of file * adds debug-view and debug-view-final * removes debug view, updates codepen instructions * adds another codepen * tutorial.md * tutorial.md * tutorial.md * tutorial.md * Put . into links for consistency with docs * Make the very first change easier to follow * A few more changes (cherry picked from commit e9d6f3f)

Jwan622 · 2017-05-24T14:17:34Z

Looks great! Sorry I wasn't able to complete my PR... was a bit busy at work. But great job!

* tutorial: adds note about onClick * tutorial: show full square component * merge * fixes line number * tutorial: misc changes * fixes Board render initial code sample * [tutorial] adds codepen links and misc small fixes * removes useless arrow functions, #9531 * {this.renderSquare} new lines * be more explicit about history state * fixes highlight * following along locally * changes todo to this.props.value * removes calculateWinner from initial codepens and includes it in tutorial * removes note about calculateWinner at end of file * adds debug-view and debug-view-final * removes debug view, updates codepen instructions * adds another codepen * tutorial.md * tutorial.md * tutorial.md * tutorial.md * Put . into links for consistency with docs * Make the very first change easier to follow * A few more changes (cherry picked from commit e9d6f3f)

brigand added 2 commits April 18, 2017 13:30

tutorial: adds note about onClick

81877ff

tutorial: show full square component

b2e9f83

facebook-github-bot added the CLA Signed label Apr 18, 2017

gaearon reviewed Apr 18, 2017

View reviewed changes

brigand added 2 commits April 18, 2017 18:17

merge

d32bf5c

fixes line number

14905fe

gaearon reviewed Apr 19, 2017

View reviewed changes

tutorial: misc changes

c5f171f

brigand commented Apr 19, 2017

View reviewed changes

gaearon reviewed Apr 20, 2017

View reviewed changes

brigand added 2 commits April 21, 2017 13:42

fixes Board render initial code sample

10facf6

[tutorial] adds codepen links and misc small fixes

f6770a4

gaearon requested changes Apr 26, 2017

View reviewed changes

gaearon mentioned this pull request Apr 26, 2017

Add a few more code-pen examples of working code #9510

Closed

removes useless arrow functions, facebook#9531

f059bb9

brigand mentioned this pull request Apr 27, 2017

Update tutorial.md #9531

Closed

brigand added 3 commits April 26, 2017 18:30

{this.renderSquare} new lines

465c3e4

be more explicit about history state

14a9fb7

fixes highlight

be5ab48

gaearon changed the title ~~[Tutorial] Square update and calling vs passing~~ [Tutorial] Make it easier to follow the instructions Apr 27, 2017

following along locally

1d2af8d

brigand commented Apr 28, 2017

View reviewed changes

brigand added 5 commits April 29, 2017 18:59

adds another codepen

9848ff6

tutorial.md

f8169ea

tutorial.md

f30cbf7

tutorial.md

d694a07

tutorial.md

737e5c4

gaearon added 4 commits May 1, 2017 14:06

Merge branch 'master' into tutorial-square-class

ed59e5c

Put . into links for consistency with docs

c938235

Make the very first change easier to follow

ff5ad1d

A few more changes

b3e90f2

gaearon approved these changes May 1, 2017

View reviewed changes

gaearon added the Documentation: needs merge to stable label May 1, 2017

gaearon merged commit e9d6f3f into facebook:master May 1, 2017

gaearon removed the Documentation: needs merge to stable label May 1, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Tutorial] Make it easier to follow the instructions #9454

[Tutorial] Make it easier to follow the instructions #9454

brigand commented Apr 18, 2017

gaearon left a comment

brigand commented Apr 19, 2017

brigand commented Apr 19, 2017

gaearon Apr 19, 2017

gaearon commented Apr 19, 2017

brigand Apr 19, 2017

brigand Apr 19, 2017

brigand commented Apr 20, 2017 •

edited

gaearon Apr 20, 2017

brigand Apr 21, 2017

brigand commented Apr 24, 2017

gaearon left a comment

gaearon Apr 26, 2017

brigand Apr 27, 2017

gaearon Apr 26, 2017 •

edited

gaearon Apr 26, 2017 •

edited

brigand Apr 27, 2017

gaearon Apr 26, 2017

brigand Apr 27, 2017

brigand commented Apr 27, 2017

gaearon commented Apr 27, 2017 •

edited

brigand Apr 28, 2017

brigand commented Apr 28, 2017

brigand commented Apr 30, 2017

gaearon commented May 1, 2017

gaearon commented May 1, 2017

Jwan622 commented May 24, 2017

		@@ -132,7 +132,7 @@ After: You should see a number in each square in the rendered output.

		### An Interactive Component

		Let's make the Square component fill in an "X" when you click it. Try changing the button tag returned in the `render()` function of the `Square` like this:

		@@ -315,19 +426,21 @@ function Square(props) {

		You'll need to change `this.props` to `props` both times it appears. Many components in your apps will be able to be written as functional components: these components tend to be easier to write and React will optimize them more in the future.

		<a href="https://codepen.io/brigand/pen/OmRoGV?editors=0010" target="_blank">View the current code</a>.

[Tutorial] Make it easier to follow the instructions #9454

[Tutorial] Make it easier to follow the instructions #9454

Conversation

brigand commented Apr 18, 2017

gaearon left a comment

Choose a reason for hiding this comment

brigand commented Apr 19, 2017

brigand commented Apr 19, 2017

Choose a reason for hiding this comment

gaearon commented Apr 19, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brigand commented Apr 20, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brigand commented Apr 24, 2017

gaearon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gaearon Apr 26, 2017 • edited

Choose a reason for hiding this comment

gaearon Apr 26, 2017 • edited

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

brigand commented Apr 27, 2017

gaearon commented Apr 27, 2017 • edited

Choose a reason for hiding this comment

brigand commented Apr 28, 2017

brigand commented Apr 30, 2017

gaearon commented May 1, 2017

gaearon commented May 1, 2017

Jwan622 commented May 24, 2017

brigand commented Apr 20, 2017 •

edited

gaearon Apr 26, 2017 •

edited

gaearon Apr 26, 2017 •

edited

gaearon commented Apr 27, 2017 •

edited