Revamp tutorial

[zpao]

We've had a huge number of issues come in here and in the tutorial repo about inconsistencies and confusing parts, especially when it sort of works fine without a server initially and then requires it half way through. We've talked about maybe rewriting it entirely and maybe we will, but in the mean time we should clean it up and make it easier for people to learn React without getting tripped up

Any ideas are welcome, especially from people on the front lines (mailing list, IRC, Slack, Stack Overflow, GitHub)

A couple ideas:

• Provide a running API server that people can use (probably with a randomly generated API key to make sure people have their own clean environment)
• Just require a local server from the beginning Done!
• Remove the tutorialN.js bit
• Paginate so that steps are separated better

[iamdustan]

Would building something similar to http://learn.knockoutjs.com/ by a possibility?

[zpao]

It would probably require a bit more effort, but yea, I think something like that could be really cool.

[AnSavvides]

A definite thumbs up on paginating. The tutorial as it is now probably looks pretty daunting to a newcomer - this has been brought up before and I usually hear this from people I refer to the docs when they ask me how they should get started with React.

What are people's thoughts on dropping jQuery in favor of window.fetch? That's removing one big library that does a lot in favor of one that does a very specific thing that we do actually need. That way, we ensure that people don't feel that jQuery is a requirement in any way, shape or form; I know there is a note already in the docs that jQuery isn't required, but including it probably is a little misleading. Also, we give people the option to total skip the tutorial and just get the code running by pointing them to the tutorial repo - in that repo, we don't explain anywhere that jQuery is there just for the sake of Ajax requests.

What do you think about moving the tutorial to be a directory within the actual React codebase? It's so easy for the two repos to get out of sync - it has happened so many times. By keeping all code in one place it's less likely that things will get out of sync. The downside is that people will have to git clone the entire React repo with all its source, but I don't think that's a bad thing - if anything, it might make it more likely that they will be curious about the actual implementation of things.

Another idea - how about having more than one tutorial? As a start, we could have three tutorials; an absolute beginner's one, one that touches on a few more advanced aspects of React and a final one which brings everything together and addresses testing React components.

[zpao]

What are people's thoughts on dropping jQuery in favor of window.fetch?

I was sort of against it when that was proposed before (it was actually the 2 of you in #3498) but meh. I'm game. We'll still have to include a polyfill but at least it's focused. My only concern is that Promises will probably be a new concept to a number of people who might not be paying close attention to JS. I think we should be ok, but wanted to mention it.

What do you think about moving the tutorial to be a directory within the actual React codebase?

Definitely upsides and downsides. Things don't change that often and while cloning the whole React repo could be good, I don't really want to put that on people. Having a pretty clean place to start is nice.

how about having more than one tutorial?

On board with that too, just need to figure out what they should be :) Fits in nicely with the knockout idea too.

[AnSavvides]

Ha, I almost forgot about that conversation around jQuery vs window.fetch. Agreed, Promises might be new to some people, but this might be a great opportunity to figure out how to explain promises in a short and concise way - it's a win-win!

Fair point on keeping the repos independent :+1:

Sweet, glad you like the sound of multiple tutorials that build you up learning more and more. Happy to help brainstorm, but from a very high level perspective it could be:

• Beginner Tutorial: Components, Lifecycle methods, Composing Components, props & state, JSX
• Intermediate Tutorial: Using React.Children utilities for manipulating, Stateful / Dynamic Children, validating props w/ React.PropTypes, Mixins, ES6 classes, inline styles
• Advanced Tutorial: PureRenderMixin, Immutability for performance, Stores, React.addons.TestUtils & using these to test React components

[gaearon]

It's gone now.