3 ms·

And that's exactly why we have a core docs "Fundamentals" tutorial that _does_ walk through the "how it works underneath", but culminates in "and now that you k

And that's exactly why we have a core docs "Fundamentals" tutorial that _does_ walk through the "how it works underneath", but culminates in "and now that you know how to write this code by hand, use RTK and never write all that extra code again: https://redux.js.org/tutorials/fundamentals/part-1-overview https://redux.js.org/tutorials/fundamentals/part-1-overview https://redux.js.org/tutorials/fundamentals/part-8-modern-redux https://redux.js.org/tutorials/fundamentals/part-8-modern-re... But, even while the "Fundamentals" tutorial does show things like hand-writing reducers and action type strings with no abstractions, it approaches teaching a lot of the common patterns differently than we used to. It doesn't talk about "action creators" until almost at the end, there's no multiple files by type, inline type strings instead of `const ADD_TODO = "ADD_TODO"`, etc. So sure, I agree that there's value in understanding how this code works by hand. But, all older tutorials and a lot of the _new_ tutorials I see still being written don't even mention RTK at all. The "Fundamentals" tutorial clearly states up front that: > The initial code will be less concise than the way we suggest writing real app code, but writing it out long-hand is the best way to learn. Once you understand how everything fits together, we'll look at using Redux Toolkit to simplify things. Redux Toolkit is the recommended way to build production apps with Redux, and is built on all of the concepts that we will look at throughout this tutorial. Once you understand the core concepts covered here, you'll understand how to use Redux Toolkit more efficiently. Meanwhile, for people who do just want to jump in and start writing something "real", the Essentials tutorial covers that learning use case. Out of curiosity, which of RTK's abstractions do you feel are "difficult to understand"?

rglover 6y ago
So, I'm confused. The links you shared covered what I covered, but your original comment made it sound as though I got it completely wrong...which doesn't seem to be the case. From what I gather, your ask is to add information about the usage of the toolkit and steer people towards that. Is that correct? If so, I don't mind adding it, but I think the existing information is helpful. Re: which abstractions are difficult to understand, the first instance of toolkit that you encounter is this: https://redux.js.org/introduction/getting-started#redux-toolkit-example https://redux.js.org/introduction/getting-started#redux-tool.... The createSlice and configureStore convention makes sense if you've used Redux before (and spend some time with it), but if you're brand new to it, the naming doesn't make it terribly clear what you're doing. The docs talk about features, but we're creating slices. What's a slice? A feature? Why not just call it createFeature? The other aspect that's confusing is that these hooks separate you from the core API quite a bit. They're obviously still there under the hood, but that disconnect means when you learn Redux now (assuming you take this blessed path), you're not really learning Redux, you're learning the abstraction that's built on top of Redux. The reason I harp on that specifically is that I teach people 1-on-1 every day and I routinely see confusion around stuff like this. You mentioned Apollo Boost in the docs somewhere as prior art and I've run into issues where both myself and people I was teaching were confused as to what it did or didn't do. From what I've observed teaching others, it helps to apply concepts in layers (like coats of paint). You're doing that somewhere in the docs as evidenced by your links, but the main Getting Started page drops devs straight into the toolkit (https://redux.js.org/introduction/getting-started#redux-toolkit-example https://redux.js.org/introduction/getting-started#redux-tool...), circumventing useful knowledge about the core of Redux. The Getting Started page is most important because, again, as I've observed people reading through docs and putting stuff together, they're big on skimming and copy/paste on first runs with new tech. This ties back in to what I mentioned above with learning the abstraction, not the core thing, which can lead to mental model issues later. For example, if I'm working on a team that's still using "old" or "wrong" stuff and a version bump isn't reasonable, and all I've learned is the toolkit method of using Redux, I'm unnecessarily stuck. If you run with the assumption that people will just linearly go through the docs, what I'm saying likely sounds crazy. But from observation, devs dart around like bees while they're learning and only pick off certain concepts as they go. The more abstractions present, the more fragmented their understanding of the tool is and the less efficacious their skillset (which leads to propagation of misunderstanding to colleagues, etc).
- acemarke 6y ago
  > From what I gather, your ask is to add information about the usage of the toolkit and steer people towards that. Is that correct? If so, I don't mind adding it, but I think the existing information is helpful. Basically, yes. The point is we want people to know that writing object spreads and action constants by hand is _not_ how they're supposed to really write Redux today, and that RTK both exists and is the standard approach for writing Redux logic. Per the "Quick Start/Getting Started" page: the point of that page is not to teach Redux or RTK. It's just the simplest possible example to show what the syntax looks like. _Learning_ this material is why we have the extensive "Essentials" and "Fundamentals" tutorials. Frankly, if having those snippets in the "Getting Started" page is confusing, I'd rather _remove_ those snippets and point more emphatically over to the tutorials. > you're not really learning Redux, you're learning the abstraction that's built on top of Redux Yes, and that's also the point. RTK _is_ now "Redux". Or rather, it's the form of Redux we want people to learn. Yes, it _is_ a set of abstractions, and some people may find it easier to learn if they understand the underlying principles and techniques first. That's why the "Fundamentals" tutorial exists. But, many other people just want to dive straight into writing working code and see "how to use it". That's why we have the "Essentials" tutorial, and there's been very positive feedback from people who _only_ read the "Essentials" tutorial to start learning Redux. (We've actually considered just replacing the NPM `redux` package with the RTK contents, but concluded that would be too much ecosystem churn: https://github.com/reduxjs/redux/issues/3321 https://github.com/reduxjs/redux/issues/3321 ). It is admittedly hard to split the learning material between our three docs sites: the Redux core docs, the Redux Toolkit docs, and the React-Redux docs. That's why I actually just deleted the tutorials in the RTK site itself recently, and instead now point to the "Essentials" and "Fundamentals" tutorials in the core site instead, so that there's no duplication of tutorial content. (There were several other issues with the RTK tutorials people had complained about anyway - see https://github.com/reduxjs/redux-toolkit/issues/371 https://github.com/reduxjs/redux-toolkit/issues/371 ). FWIW, this is a really good discussion and set of feedback, and I appreciate you engaging with me on this :) If you still have concerns about how we're trying to teach Redux and RTK, could you do me a favor and file a new "Discussion" in the Redux core repo, at https://github.com/reduxjs/redux/discussions https://github.com/reduxjs/redux/discussions ? I definitely take concerns over Redux learning flow seriously and am interested in ways we can improve the docs, and this HN thread probably isn't the best place for surfacing the discussion :)

rglover 6y ago

So, I'm confused. The links you shared covered what I covered, but your original comment made it sound as though I got it completely wrong...which doesn't seem to be the case. From what I gather, your ask is to add information about the usage of the toolkit and steer people towards that. Is that correct? If so, I don't mind adding it, but I think the existing information is helpful. Re: which abstractions are difficult to understand, the first instance of toolkit that you encounter is this: https://redux.js.org/introduction/getting-started#redux-toolkit-example https://redux.js.org/introduction/getting-started#redux-tool.... The createSlice and configureStore convention makes sense if you've used Redux before (and spend some time with it), but if you're brand new to it, the naming doesn't make it terribly clear what you're doing. The docs talk about features, but we're creating slices. What's a slice? A feature? Why not just call it createFeature? The other aspect that's confusing is that these hooks separate you from the core API quite a bit. They're obviously still there under the hood, but that disconnect means when you learn Redux now (assuming you take this blessed path), you're not really learning Redux, you're learning the abstraction that's built on top of Redux. The reason I harp on that specifically is that I teach people 1-on-1 every day and I routinely see confusion around stuff like this. You mentioned Apollo Boost in the docs somewhere as prior art and I've run into issues where both myself and people I was teaching were confused as to what it did or didn't do. From what I've observed teaching others, it helps to apply concepts in layers (like coats of paint). You're doing that somewhere in the docs as evidenced by your links, but the main Getting Started page drops devs straight into the toolkit (https://redux.js.org/introduction/getting-started#redux-toolkit-example https://redux.js.org/introduction/getting-started#redux-tool...), circumventing useful knowledge about the core of Redux. The Getting Started page is most important because, again, as I've observed people reading through docs and putting stuff together, they're big on skimming and copy/paste on first runs with new tech. This ties back in to what I mentioned above with learning the abstraction, not the core thing, which can lead to mental model issues later. For example, if I'm working on a team that's still using "old" or "wrong" stuff and a version bump isn't reasonable, and all I've learned is the toolkit method of using Redux, I'm unnecessarily stuck. If you run with the assumption that people will just linearly go through the docs, what I'm saying likely sounds crazy. But from observation, devs dart around like bees while they're learning and only pick off certain concepts as they go. The more abstractions present, the more fragmented their understanding of the tool is and the less efficacious their skillset (which leads to propagation of misunderstanding to colleagues, etc).

acemarke 6y ago
> From what I gather, your ask is to add information about the usage of the toolkit and steer people towards that. Is that correct? If so, I don't mind adding it, but I think the existing information is helpful. Basically, yes. The point is we want people to know that writing object spreads and action constants by hand is _not_ how they're supposed to really write Redux today, and that RTK both exists and is the standard approach for writing Redux logic. Per the "Quick Start/Getting Started" page: the point of that page is not to teach Redux or RTK. It's just the simplest possible example to show what the syntax looks like. _Learning_ this material is why we have the extensive "Essentials" and "Fundamentals" tutorials. Frankly, if having those snippets in the "Getting Started" page is confusing, I'd rather _remove_ those snippets and point more emphatically over to the tutorials. > you're not really learning Redux, you're learning the abstraction that's built on top of Redux Yes, and that's also the point. RTK _is_ now "Redux". Or rather, it's the form of Redux we want people to learn. Yes, it _is_ a set of abstractions, and some people may find it easier to learn if they understand the underlying principles and techniques first. That's why the "Fundamentals" tutorial exists. But, many other people just want to dive straight into writing working code and see "how to use it". That's why we have the "Essentials" tutorial, and there's been very positive feedback from people who _only_ read the "Essentials" tutorial to start learning Redux. (We've actually considered just replacing the NPM `redux` package with the RTK contents, but concluded that would be too much ecosystem churn: https://github.com/reduxjs/redux/issues/3321 https://github.com/reduxjs/redux/issues/3321 ). It is admittedly hard to split the learning material between our three docs sites: the Redux core docs, the Redux Toolkit docs, and the React-Redux docs. That's why I actually just deleted the tutorials in the RTK site itself recently, and instead now point to the "Essentials" and "Fundamentals" tutorials in the core site instead, so that there's no duplication of tutorial content. (There were several other issues with the RTK tutorials people had complained about anyway - see https://github.com/reduxjs/redux-toolkit/issues/371 https://github.com/reduxjs/redux-toolkit/issues/371 ). FWIW, this is a really good discussion and set of feedback, and I appreciate you engaging with me on this :) If you still have concerns about how we're trying to teach Redux and RTK, could you do me a favor and file a new "Discussion" in the Redux core repo, at https://github.com/reduxjs/redux/discussions https://github.com/reduxjs/redux/discussions ? I definitely take concerns over Redux learning flow seriously and am interested in ways we can improve the docs, and this HN thread probably isn't the best place for surfacing the discussion :)