Docs: Clarify Redux specific concepts

[peteruithoven]

Getting into Redux I started with the TodoList example, where I really struggled with new concepts that are not really explained in comments or (new) docs, just yet.
I found another issue with basically the same question, which was already closed; #134 where gaearon shortly tries to explain these concepts.

Disclaimer; this might be mostly a problem from people that are trying to learn Redux from examples.

Compared to just using React, I see 3 extra steps:

1. App component, with a Provider (what is that?) (could use a comment and/or page in docs?), which retrieves another component (TodoApp) through a function? (comments say because of an issue with 0.13, but this is still relevant for 1.0?) (I can't find explanation why this is needed?)
2. TodoApp then contains a connector (what is that?) (I remember seeing that work as a decorator in other places?) which selects specific data from the bigger app state (right?) (could use a comment and page in docs?).
3. This connector also calls a function which gets the selected state (right?) and dispatch function (right?). This function then retrieves actions through a bindActionCreators (which does what?) and forwards these actions to the actual components. (This whole step feels unwieldy and could really use come comments?)

Compared to React and Flux I see 3 new concepts:

1. Providers (What do they do?)
2. Connector & select mechanism (What does it do? Why can't I just forward the same dispatch function and a portion of the state?)
3. bindActionCreator mechanism (Explained in http://gaearon.github.io/redux/docs/api/bindActionCreators.html)

Don't some of these concepts deserve some pages in the Basics section of the new docs?

Probably relevant for: #349 (Rewrite docs (again!))

[gaearon]

Do these docs help?

https://github.com/gaearon/react-redux

I wanted to show a walkthrough rather than dive into details of the API decisions of another project.

[peteruithoven]

Thanks for the quick reply!
Which "another project" are you referring to?

[gaearon]

react-redux: https://github.com/gaearon/react-redux
It's a separate project.

[peteruithoven]

Ah okay, that makes sense. But It's quite a step when you're also trying to understand a new framework.

Those docs really do explain Providers and Connectors quite well, I now also found the new Usage with React documentation (new docs are looking very good btw!)

Maybe simply referring to that Usage with react page more often would make getting into Redux easier. I'll try to do some pull requests with more concrete suggestions.

[gaearon]

Those docs really do explain Providers and Connectors quite well, I now also found the new Usage with React documentation (new docs are looking very good btw!)

Oh.. I assumed you've read it because it went before “Example” page. Maybe I should just rename “Example” to “Source Code” to clarify that one needs to read all previous steps to understand it.

[peteruithoven]

I think we're stumbling on a different way of learning, I was lazy and tried to skip steps ;) I tried to learn from the todo example instead of the docs. Working from the example I was having a hard time finding the right documentation for the parts I didn't understand. I guess I expected a Provider chapter, but it was React specific and thus part of Usage with React.
Adding comments with basic explanations and links would really help. And seeing you're comment in my pull request you agree. Thanks!

[gaearon]

I got it. I'll keep this in mind and update the examples later to include links.