Improve "Essentials" and "Fundamentals" tutorial instructions and differentiation

[markerikson]

Per Laurie Voss:

• https://mastodon.social/@seldo@alpaca.gold/109973908464601519

The official "how to use Redux" tutorial is literally 7 hours of "here's how to do it" followed immediately by a part 8 which is "j/k you don't need to do any of that stuff we wrote a library" and I have some feedback on the structure of this documentation.

Further feedback:

• https://mastodon.social/@seldo@alpaca.gold/109976972365346083 and following

So, coming into it from nowhere, there's little indication about whether "essentials" or "fundamentals" are a better place to start. The end of the "quick start" suggests doing both without saying in what order or how they differ (the tutorials index page does, but I didn't find that page until I was writing this message).

Google searches for how to do various things in redux kept landing me on Fundamentals and not on Essentials.

RTK Query was described as "new" and "not essential" so I avoided the Essentials tutorial on the basis that it was introducing more concepts than I seemed to need at once.

The introduction section clearly says "Redux toolkit is how you should learn redux" (https://redux.js.org/introduction/why-rtk-is-redux-today) (good!) but nowhere does it say "Redux essentials is the tutorial that teaches you how to use redux toolkit" and nowhere in the outline of Essentials is the word "toolkit" (unless you know in advance what RTK stands for).

[timdorr]

Is there any reason to have these two tutorials in the docs? Fundamentals made sense when we didn't have RTK to apply good abstractions and patterns. Understanding the reasoning was important so folks built a solid foundation for their apps. Now that we provide that out of the box for them, it seems like that is less needed.

[markerikson]

@timdorr : yes, because they target different audiences and have different purposes:

• "Essentials": goes straight into "here's how we want you to use Redux, with RTK"; shows all RTK APIs in the course of building out a real-world-ish app; intentionally skips the "how does any of this work inside" part
• "Fundamentals": focuses on "how does this work, piece by piece, from the bottom up, without any abstractions"

Everyone should go through "Essentials". But there's plenty of people out there who feel like they need to understand how something works before they can successfully use it, and "Fundamentals" is meant to cover that audience. Alternately, someone has gone through "Essentials" and understands the usage patterns, but wants to know why RTK is designed this way and what it's doing for them.

So, both useful.

[phryneas]

Maybe "Fundamentals" could be renamed to "internals" or something? 🤔

[timdorr]

But since we've marked createStore as deprecated, that seems somewhat contradictory to me. If people need a deep dive, can't we just add that under Understand Redux?

[markerikson]

It's deprecated because we don't want people actively using it.

But the point of the tutorial is to walk people through the pieces that make up Redux, step by step, to help get across all the concepts. It's a "teaching" section, not an "explanation" section:

• https://documentation.divio.com/tutorials/
• https://documentation.divio.com/explanation/

And given that createStore is really the heart of Redux, and it is how you would use Redux if you weren't using the RTK abstractions around it, it makes sense to cover it in this tutorial.