4 ms·

The tutorial asks you to either use CodePen (which requires no build tooling) or Create React App (which requires you to run a command in the terminal but then

The tutorial asks you to either use CodePen (which requires no build tooling) or Create React App (which requires you to run a command in the terminal but then you don't need to configure anything): https://reactjs.org/tutorial/tutorial.html#how-to-follow-along https://reactjs.org/tutorial/tutorial.html#how-to-follow-alo... Similarly, the installation page offers you to either download a single HTML file, or to install a CLI that gives you a project that's ready to go: https://reactjs.org/docs/installation.html https://reactjs.org/docs/installation.html Could you clarify what give you an impression that you need to have a deep knowledge of build tooling to follow along?

mcintyre1994 9y ago
Hey Dan, I really appreciate you responding here - I know things like Create React App have come in the past couple years, and that people love it - I'm not trying to take anything away from what you've built. I know the way I learned React isn't how anybody is ever going to make anything production quality. I'll try to clarify. If you don't mind another comparison to Vue, their equivalent page: https://vuejs.org/v2/guide/ https://vuejs.org/v2/guide/ says "Or, you can create an index.html file and include Vue with: <script src="https://unpkg.com/vue"></script>" https://unpkg.com/vue"></script>", while your get started page says "If you’d rather use a local development environment, check out the Installation page." I know, if I click there it'll say I have an index.html and I know I shouldn't do it that way, but if I have none of the infrastructure on my computer and I want to build my thing on my computer, I'm looking for the script - not installation instructions. On that 'how to follow along' page, under prerequisites it says "Note that we’re also using some features from ES6, a recent version of JavaScript. In this tutorial, we’re using arrow functions, classes, let, and const statements. You can use Babel REPL to check what ES6 code compiles to.". If this was the first React tutorial I ever looked at I'd be completely lost here and concluding I don't understand the prerequisites. If I know anything about 'relatively new' things in Javascript or Babel then I assume that I'm expected to use it somehow to actually use those relatively new things in my browser, but I have no idea how. Also, scrolling down a bit, "if you prefer to write code in your editor" is a list of 6 steps, one of which is installing Node and another is "Follow the installation instructions to create a new project." I might not need deep knowledge, but this feels like a lot of stuff to do to follow a tutorial in my editor. Here's my story about the old, do-it-all-locally tutorial: I'd just started an internship, and got a brief about doing some dynamic UI generation from schemas in .net stuff I'd never used, and was meant to be designing a schema to use. I had no idea what that should look like, so I learned React with your old tutorial and within a few hours could iterate on a schema to build UI components like theirs in the browser. This was amazingly helpful to me, and looked way more impressive than it actually was when I showed the boss! I just doubt that I'd do that based on your current tutorial, because I'd be on a Windows machine and get hung up installing NPM or something silly.. and that feels like a shame to me.
- danabramov 9y ago
  Thanks for sharing the concerns. It's a bit of a tough balance. For example before we mentioned the prerequisites like understanding ES5 and basics of ES6, people were complaining that we don't make the assumed knowledge clear. Before we used ES6, people were complaining our code doesn't look like the ones they see in examples and docs for other libraries. Et cetera. Somebody always is upset, although maybe we're just doing a bad job. :-( We do offer an HTML file to download that you can tinker with, but only on "Installation" page rather than the Tutorial. Maybe we can unify them somehow. Overall, it's frustrating that people tell us about these issues once a year when we release something, instead of raising an issue and discussing it there. :-) If somebody told us on GitHub this is a problem, we would have fixed it a long time ago.
  - mcintyre1994 9y ago
    I agree it's a tough balance, and I definitely wouldn't say you're doing a bad job, I hope I don't come across like I think that you are! I appreciate that frustration, I didn't raise this as a Github issue because it didn't feel actionable and I don't want to spam all your maintainers with a complaint without having something more concrete to suggest. I'll try to put something together though if that'd be useful :)
acemarke 9y ago
Dan, it might be worth throwing in links to CodeSandbox/StackBlitz/WebpackBin somewhere obvious in addition to CodePen, since each of those are online IDEs oriented towards working with React.

mcintyre1994 9y ago

Hey Dan, I really appreciate you responding here - I know things like Create React App have come in the past couple years, and that people love it - I'm not trying to take anything away from what you've built. I know the way I learned React isn't how anybody is ever going to make anything production quality. I'll try to clarify. If you don't mind another comparison to Vue, their equivalent page: https://vuejs.org/v2/guide/ https://vuejs.org/v2/guide/ says "Or, you can create an index.html file and include Vue with: <script src="https://unpkg.com/vue"></script>" https://unpkg.com/vue"></script>", while your get started page says "If you’d rather use a local development environment, check out the Installation page." I know, if I click there it'll say I have an index.html and I know I shouldn't do it that way, but if I have none of the infrastructure on my computer and I want to build my thing on my computer, I'm looking for the script - not installation instructions. On that 'how to follow along' page, under prerequisites it says "Note that we’re also using some features from ES6, a recent version of JavaScript. In this tutorial, we’re using arrow functions, classes, let, and const statements. You can use Babel REPL to check what ES6 code compiles to.". If this was the first React tutorial I ever looked at I'd be completely lost here and concluding I don't understand the prerequisites. If I know anything about 'relatively new' things in Javascript or Babel then I assume that I'm expected to use it somehow to actually use those relatively new things in my browser, but I have no idea how. Also, scrolling down a bit, "if you prefer to write code in your editor" is a list of 6 steps, one of which is installing Node and another is "Follow the installation instructions to create a new project." I might not need deep knowledge, but this feels like a lot of stuff to do to follow a tutorial in my editor. Here's my story about the old, do-it-all-locally tutorial: I'd just started an internship, and got a brief about doing some dynamic UI generation from schemas in .net stuff I'd never used, and was meant to be designing a schema to use. I had no idea what that should look like, so I learned React with your old tutorial and within a few hours could iterate on a schema to build UI components like theirs in the browser. This was amazingly helpful to me, and looked way more impressive than it actually was when I showed the boss! I just doubt that I'd do that based on your current tutorial, because I'd be on a Windows machine and get hung up installing NPM or something silly.. and that feels like a shame to me.

danabramov 9y ago
Thanks for sharing the concerns. It's a bit of a tough balance. For example before we mentioned the prerequisites like understanding ES5 and basics of ES6, people were complaining that we don't make the assumed knowledge clear. Before we used ES6, people were complaining our code doesn't look like the ones they see in examples and docs for other libraries. Et cetera. Somebody always is upset, although maybe we're just doing a bad job. :-( We do offer an HTML file to download that you can tinker with, but only on "Installation" page rather than the Tutorial. Maybe we can unify them somehow. Overall, it's frustrating that people tell us about these issues once a year when we release something, instead of raising an issue and discussing it there. :-) If somebody told us on GitHub this is a problem, we would have fixed it a long time ago.
- mcintyre1994 9y ago
  I agree it's a tough balance, and I definitely wouldn't say you're doing a bad job, I hope I don't come across like I think that you are! I appreciate that frustration, I didn't raise this as a Github issue because it didn't feel actionable and I don't want to spam all your maintainers with a complaint without having something more concrete to suggest. I'll try to put something together though if that'd be useful :)

acemarke 9y ago

Dan, it might be worth throwing in links to CodeSandbox/StackBlitz/WebpackBin somewhere obvious in addition to CodePen, since each of those are online IDEs oriented towards working with React.