[hnbreak]

I meant the docs. It's like decades ago like when you wanted to learn Rails. Then somebody said stop! First learn Ruby... This is not how people learn. There's too much time between learning and trying, so there's no proper and face-paced feedback loop. Let's try to get into somebody's head who's ok in react and slowly wants to get into state management but having no clue of nothing:

His mind:

- Ok, where should I start?

- Which is the best? Mobx, redux, just ContextProvider or local state??

The poor guys falls into the rabbit hole and reads Reddit, HN, Github issues for hours, still not sure what to do; 2 hours later

- Ok, let's try redux, for whatever reason, the maintainers seem to be quite active

The poor guy tries to decide if he should go just with redux/react-redux or rtk; former because it is good to understand the foundation, latter good because just to avoid boilerplate and that's what this acemark is promoting everywhere. The guy is still overwhelmed and don't forget doing decision is hard; it's one of the biggest struggles for humans

- Ok, I guess I need to start with redux because it's the foundation.

He sees all the theory, new terms, the boilerplate and there's no fast-paced feedback loop; he just think heck and checks out mobx, 4 hours later

- Man mobx is even more weird, totally unstructured and while mobx's maintainer seems to be a nice guy, my gut feeling is: stay away

- Let's check out npmtrends, oh great, npmtrends shows that people also don't like mobx, cool, it has much less traction, decision made, nice

- So, let's try redux again, maybe this time I start with RTK

We know what happens, RTK has better feedback loops but w/o the basic knowledge of redux he will struggle, 6 hours later after jumping back and forth the both docs

- Lets stop here, tomorrow is another day.

He is out of flow, motivation is down, the next day he doesn't continue because the whole experience didn't feel good, he writes a post on HN that redux sucks steel and maybe looks the next week again on it

The situation is a bit like with kubernetes; until you have proper feedback loops with k8s you need days, with new k8s distros this got better but the biggest bummer are the k8s docs, too much, too verbose, so many new terms, no feedback loops at all and every k8s examples has minimum 100kb yamls.

What would be great and I know that writing good docs is much harder than actual code:

One and only piece which the reader should read first, which teaches him redux foundation, react-redux boilerplate and rtk within max 2 hours. After that he should have a working example AND should have understood it. No links to other resources, no nothing.

This main piece should be linked everywhere in the Github readmes of all redux relates projects in bold and h1 READ OUR MAIN PIECE FIRST, on all the doc pages and in all forum posts. I mean look at your post's footer in this thread: so many links, why? You need one entry point. RTK could be the entry point, it just needs a bit more flesh on redux and should be declared as the entry point of redux. There's one disadvantage though: with RTK as entry you'd kill the ecosystem around redux but IDK if you did this anyway by declaring RTK the standard way. And you would have a lot of redundant docs with redux/react-redux. Or maybe we need to merge all because maintaining redundant docs is just too much for an OSS project.

Whatever, all not easy but there must be a way because redux is the most underrated thing in the frontend world, it's def the best state management and RTK is a nice and long deserved abstraction.

[yowlingcat]

Great and substantive comment. Docs should be example and results driven or they're not really docs. Django and now Rails do a good job of this, in part because they're frameworks. But even for something of the size of Redux, it would be fantastic to see a basic mobile todo app with a navigation bar and a basic logged in/logged out mode built from scratch to show you how to manage state in the real world.

[acemarke]

Thanks for the feedback. I've pasted it into our "Docs Rewrite: Overview" issue for reference [0].

Responding a bit further:

There's not much we can do about folks going back and forth between Redux and various non-Redux-y things. That's outside of our scope and ability to help with.

Teaching-wise, there's several reasons why the docs are structured the way they are right now:

- Redux itself is an independent library that is not tied to React in any way (and is used with other frameworks / UI layers as well). Our docs do mostly assume that you're using React, but the tutorials start out trying to show how you'd use Redux without any UI layer, to teach the basic concepts.

- React-Redux has been a separate library from Redux itself since it hit 1.0. While we do teach the basics of how to use React-Redux in the Redux core docs, it has its own separate repo and separate docs site. Similarly, RTK was designed as an addon layer around the Redux core, so it also has a separate repo and separate docs site, and its docs assume that you understand the basics of Redux already.

- That said, yes, the vast majority of Redux usage _is_ with React, and we are encouraging folks to use RTK as the default way to write Redux logic. So, it's very reasonable to have a docs page that shows how to jump right into using both of them as fast as possible. This is something I've already said I want to add to the docs, as a "Quick Start" page [1].

In terms of teaching flow and learning, there's various ways to approach explaining things. Dan Abramov wrote the original Redux docs content and structure, and his teaching style is very much "bottom-up, from first principles". You can see that style in pages like the current "Middleware" tutorial page [2], and his Redux videos on Egghead [3]. That approach works great for some people, but other folks just want to be shown _how_ to do something first, and learn the "why" later. It's hard to serve both groups at the same time.

One issue with teaching RTK first is that while Redux requires / expects that you use immutability correctly, RTK's use of Immer does hide the fact that immutable updates are happening in the background. It would be easy for someone who learns Redux via RTK to assume that writing mutating logic _is_ the right way to write reducers, not realize that it only works right due to the "magic" inside RTK's APIs, and then go write reducers in another project without RTK that are completely buggy as a result. I haven't yet entirely figured out how to handle that aspect, other than plastering warning notes all over the docs. That's one reason why I would prefer that folks understand the core principles first and how to do things by hand, and then switch to RTK to write the same code in simpler form.

As I said earlier, there's good reasons why we have separate libraries and separate docs sites. I can hypothetically imagine pulling things together into a combined docs site, similar to how NgRx does it [4]. But, I'm not sure how technically feasible it would be. It might require restructuring everything into a mono-repo, and I don't think I want to have to figure out how to migrate everything at this point.

All that said, yes, part of the goals for this Redux core docs rewrite is to provide a much more obvious learning path.

Finally, no, I don't think RTK is "killing the ecosystem around Redux", as the ecosystem is much broader than what RTK includes. RTK does obsolete a lot of similar libraries, but there's many other pieces out there for other use cases.

[0] https://github.com/reduxjs/redux/issues/3592#issuecomment-57...

[1] https://github.com/reduxjs/redux/issues/3594

[2] https://redux.js.org/advanced/middleware

[3] https://egghead.io/series/getting-started-with-redux

[4] https://ngrx.io/docs

[hnbreak]

Thanks for your reply. Man, so much legacy, now I get it better. The Quick Start sounds like a good next step and some low hanging fruit!

ps and to understand your That's outside of our scope and ability to help with. better: Are you not also maintainer of redux and react-redux?

[acemarke]

Yes, I'm a Redux maintainer. My point is that I can't do anything to prevent folks from asking "what state management approach should I use?", looking at NPM trends, reading other tutorials that espouse differing approaches, or jumping back and forth between the React, MobX, and Redux docs sites. All we can do is try to provide as much helpful info in our own docs, and even that assumes that folks even _read_ the Redux docs. I see a lot of people asking "I want to learn $TOOL, what's the best course on Udemy?", and not even looking at the actual docs for $TOOL at all. Doesn't matter how good the docs are if people don't read them :(