Tutorial needs to focus, too scattered and difficult to get started

[mkirklions]

I hope redux authors can take this as constructive criticism.

I am using redux, thank you for that.

I take issue with the tutorial. The number of steps and backtracking to run your first Redux application was unacceptable. The tutorials I found on Medium were significantly better at getting Redux started quick, and explaining the components needed in an action, reducer, etc...

The tutorial was written with the understanding that you had experience with Flux. The tutorial was far too long before you could run a program.

People need to play to fully understand. By the time I was 'playing', the tutorial example never worked and I moved onto Medium for learning redux.

I think the tutorial needs to be completely re-written. Redux in 20 minutes and redux with networking would both be very useful.

I hope you can find value in this comment. I find the package great to solve my JS problems, but the tutorial needs improvement.

[markerikson]

The main tutorial structure was written when Redux first came out. At that time, many people were familiar with Flux, and so part of the intent was to explain how Redux was different from other Flux libraries. Dan Abramov wrote some tweets describing how hard it was to balance the different audiences for the docs. It's also hard to balance for people with different learning styles. Dan's teaching style is very much "explain things from first principles".

I'd agree that the situation has probably changed by now. Almost no one remembers what "Flux" was, and the target audience is likely to be different.

I've already got an open issue at #2590 suggesting we rethink the docs structure as a whole. Unfortunately, we don't have time to focus on a docs revamp ourselves at the moment, but I'd be happy to work with you or anyone else who wants to contribute improvements.

[imanushree]

Hi mark, I would love to help you out with this issue. Let me take a look at the existing tutorial, the suggestions in #2590 and come up with a list of things to discuss with you :)

[dwhite96]

I noticed today that bulleted items in the docs render with the bullet aligned with the last line of text for each bulleted item. This is not a big deal but can be distracting. I also thought that this didn't require a new issue. I found this "docs" issue was pretty recent and may be a good place to point this out.

[hedgerh]

What's the current status on this? I'll walk through it and see if I can improve it.

[markerikson]

@hedgerh : don't think anyone's actively doing anything with this. Would be happy to have someone get involved.

[JoviDeCroock]

What i had in mind is making a quick start guide with react-redux and with something to handling side effects (be it redux-thunk, ...)

As for the flux refs, i'm not really finding that much of them.

[markerikson]

@JoviDeCroock : yes, a quick-start guide would be great!

[dr3adl0rd]

I agree with the OP, the tutorial is unacceptable, and since I don't have any Flux experience at all, I have no idea what the comparison is about. Also, the todo example is waaay too large for the first timer.
When I was learning Vue.js at vuemastery.com I went through their tutorials in no time, they completely stole my attention with small step by step tutorials. Have a look at that, as I think it's one of the best I've seen around.
It doesn't always have to be text to make it clear and easy to start with, videos of IDE with explanations + code on the page are much much better, as I can code what they talk about at the same time.

[ofbeaton]

I came here to open an issue about the docs, found this one. I'm not sure if I should post in #2933 or #2590 but I chose here because users are posting here vs contributors there.

I'm a newbie just went through react beginner tutorial. Then I came here and clicked Basic Tutorial.

I am very grateful there are docs. That in itself is fantastic. Thank you.

That said, I had some big problems with the "basic tutorial"

• There is near-zero time spent explaining environment setup for the tutorial itself. There are output screenshots from browsers running the code but no time dedicated to telling you how to get this running in the browser. I'm not saying it's impossible to figure out on my own, but coming from cra, which this tutorial does not use, a basics tutorial really should cover this. If you want to avoid it by linking to sandboxes only that's fine, then explain how to get it running there and link there.
• The code in the tutorial doesn't clearly indicate what file you are editing so you can follow along. They often only say at the end of the section.
• The start builds on top of knowledge it assumes you have of flux by just telling you how it differs from the flux concept, not explaining the concept itself.
• There is a ton of "Squirrel!" distractions from a simple streamlined flow through the tutorial for a beginner. A basics tutorial should not be so concerned at linking me to hour long talks, other tutorials, complete other libraries so much. Some "extra info this way" is expected, but I felt constantly conflicted if I should continue this tutorial or I needed to go spend several days elsewhere and come back.

While I understand there are a lot of other tutorials out there that do a good job, I came to the official page first and I saw an official basics tutorial so that's what I tried to start with.

It wasn't a good experience.

[markerikson]

@ofbeaton : thanks for providing this feedback! I appreciate you taking the time to comment, and those are some good thoughts.

FWIW, skimming your comment, I think I agree with most of your points. We do actually already have plans to completely revamp the docs. Unfortunately, there's other priorities atm, and we haven't been able to get started on that task yet.

If you're interested, I've written up my proposed approach for reorganizing and rewriting the docs here:

#3313 (comment)

I'd be interested in hearing your thoughts on whether any of that sounds better. (No worries if you don't have time or the suggestions don't mean anything to you yet - just curious to hear your thoughts.)

All that said: our usual recommendation is that most folks should focus on learning React first, and then pick up Redux after you're already comfortable with React. Based on your comment, it sounds like you're still very new to React. You're totally welcome to learn Redux whenever you want, it's just usually easier to focus on one thing at a time.

[ofbeaton]

@markerikson Thank you for being so welcoming. I know it can be frustrating having users complain.

I've read your comment there (it was long!) Overall I think it is a great plan. However.

It seems insanely ambitious and huge. Given how your first response was that you have other priorities atm (understandable), my suggestion would be to try to pare it down to something that is actionable and has value in the shorter term.

For example you might decide that given current efforts it is not realistic to keep a basic tutorial for beginners, and an advanced tutorial. That as the official documentation, you are there as a reference and source of truth, not to teach people and hold their hand. You could choose to point people to community efforts (maybe react-redux or redux-starter-kit) or not. Just host reference documentation.

If you decided to keep the tutorials, then I would expect them to be opinionated. I don't want to know the 10 different ways of doing this, the why it was designed a certain way, etc. I want you to pick one path, even if it's not "more correct" and show me how to use it while making as few assumptions of me as is reasonable (ha!).

Maybe you can have an info bubble with some links to more advanced docs but generally just saying there are other ways of doing things is enough. That is what the advanced docs are for.

Your focus on trying to get everything into a js sandbox I think will force you to make sure that people can actually follow along with the examples, and run them. Which were 2 of my complaints.

Good luck, and I hope to be around long enough to be able to contribute more substantially in the future!

I'm about 4 weekends into my react forray and loving it so far. Can't wait to see what Redux has to offer me. (My path so far)

[timdorr]

Closing in favor of #3592