React: Storing A History Incomplete

[Kspen]

When user gets to the "Storing A History" part of the React tutorial, the user can easily get lost, as the tutorial briefly becomes vague and without example, at the point of text shown below."

"Then remove the constructor from Board and change Board so that it takes squares via props and has its own onClick prop specified by Game, like the transformation we made for Square earlier. You can pass the location of each square into the click handler so that we still know which square was clicked:"

The tutorial should reiterate the steps, displaying the final code after Board has been edited as described. "...so that it takes squares via props and has its own onClick prop specified by Game" is vague and to someone who has never used React before. This step is "easier said than done", and does not conform to the level of explanation with examples that the previous portions of the tutorial exhibit.

Long story short, this point in the tutorial is where it "falls apart", and users are likely to just stop out of confusion, and move on to some other tutorial. This seems to be a critical stepping point that should be "ironed out" to be more clear and concise.

[acdlite]

Thanks for the feedback. Would you like to submit a PR with specific edits you'd like to see?

[Kspen]

Thanks for the reply. To be honest, I just started trying to learn React today, so I'm not qualified to provide any edits. I just know that I got lost there at the end, and wasn't exactly sure what I was being told to do, thus unable to complete the tutorial.

Removing the constructor from the Board class is self-explanatory but the rest of the sentence would greatly benefit from the addition of another Code div, showing what Board looks like after the suggested changes are made. Personally, it would help me better understand what refactoring is to occur during this step, as well as a better understanding of how these properties are getting passed around. While I'm well versed in other languages, JS is not my strong suit (working to resolve that deficiency now.)

It is likely that, after a few other tutorials, I can come back and figure this one out but have suggested these edits since this is basically _"the"_ introductory React tutorial.

[gaearon]

Assigned to @lacker since he should have context from all the other PRs to Tutorial:
https://github.com/facebook/react/pulls/assigned/lacker

[TAGraves]

I'd be happy to take a stab at rewriting / clarifying this section if no one else is working on it.

[lacker]

So there is a PR pending with a bunch of refactoring that includes this part of the docs at https://github.com/facebook/react/pull/8795 . Do you think that PR is an improvement? A lot of these sorts of changes seem somewhat stylistic and could go either way, and if we walk people through every step the tutorial will get too verbose, so I'm curious to get more feedback on that one.

[Yush0]

Got stuck there too.
What should we exactly do with board? Make it a function like square and use props as parameters? Ok. But what happens to the functions inside of board?
I am completely new to react and some clarification in the tutorial would be really helpful.

[Kspen]

8795 looks like a hot mess of back and forth. Showing us what to do rather than vaguely stating, "Then remove the constructor from Board and change Board so that it takes squares via props and has its own onClick prop specified by Game, like the transformation we made for Square earlier. You can pass the location of each square into the click handler so that we still know which square was clicked:"

This makes a load of assumptions, primarily assuming the reader has ever done anything with React. The fail point of this tutorial is the above quoted sentence, with no sample of the "after" code, as seen previously in the tutorial. This entire tutorial is essentially useless if a beginner cannot complete it without having to guess, and eventually give up.

One thing I've learned about teaching people is that you can never really be too verbose. And if you attempt to teach someone and they don't understand when you are done, then you weren't verbose enough, and thus failed at teaching them anything. If you want a quick solution, just delete Storing a History and everything after it.

[lacker]

@Kspen if you have feedback about the "hot mess" of https://github.com/facebook/react/pull/8795 can you provide it on that pull request? In general I think the nature of these tutorials is more judgment-based than most code so we might just end up with something that doesn't satisfy everyone, but maybe there actually is something that would make the different sides happy and your feedback after all is the most honest real feedback from someone really using this tutorial.

[Kspen]

@lacker Thanks for the response. I think maybe a better option for an initial introductory tutorial would be a variant of https://www.kirupa.com/react/creating_single_page_app_react_using_react_router.htm . A variant of this from the official React maintainers would be great. Basically, the new tutorial would read as, "Here is a static HTML file. Now we add the script src, with explanation of what each script source is (what is react.js vs react-dom.js). Now we convert this simple static HTML into a simple static React SPA. Next, we convert it to use a remote data source, via fetch."

The way I see it, this is "the" React tutorial. While it exists to provide a working example for purposes of learning, its main goal is actually to sell the technology. The idea I'm proposing aims to be a more concrete, practical example, with intentions of showing both how to code in React as well as what is is and how it works (explaining react.js/react-dom.js split). Or maybe another way to say it would be to "how to code in React, explain what the moving parts are and how they work together, and how to think in React terms."

Hope this helps.

Regards,

[gaearon]

@brigand and I rewrote some parts of the tutorial in https://github.com/facebook/react/issues/9454, and following along should be easier now. Let us know if you're still struggling! We’re happy to look at remaining issues in case we missed anything.

https://facebook.github.io/react/tutorial/tutorial.html