Meta-question: Onboarding through documentation

[greebl3]

Hi,

Curious what the team's stance is re: maintaining different domains and knowledge bases for Core vs RTK.

Given how hard the maintainers have been advocating for RTK usage, even for non-noobs, do you have any plans on folding the RTK docs into the main Redux docs (which I imagine is what most users land on first).

Seeing threads like this makes it clear that the Redux team has thought closely about the developer experience, especially for first-time users, so any clarity on this from a high-level would be appreciated as it would help me (and I'm sure many others) contextualize future PRs.

Pinging @markerikson specifically since he seems to be spearheading a lot of these docs-rewrite initiatives

[markerikson]

Yeah, the big issue here is that for very valid historical reasons, we have three separate libraries, each with their own repos:

• https://github.com/reduxjs/redux / redux: the original Redux core lib . No real further dev work is happening here (although we've got a TS conversion that's been sitting in master since 2019 that we've never published).
• https://github.com/reduxjs/react-redux / react-redux: the React-Redux UI bindings lib. Still under active maintenance, although now that v8 is out there's no immediate plans for further dev work.
• https://github.com/reduxjs/redux-toolkit / @reduxjs/toolkit: wraps redux, and it's where all the active dev work is happening

Because of this, we also have three distinct docs sites:

• https://redux.js.org : the original Redux docs site. Has the main tutorials, the API docs for redux, and the general usage guides for things like "writing tests", "using thunks/selectors", "organizing reducers", etc
• https://react-redux.js.org : the React-Redux docs. These were originally just Markdown files in the repo - we didn't set up as an actual docs site until like 2018-ish. Has an old outdated tutorial on using connect, the API docs for hooks and connect, and a couple usage guides on using connect.
• https://redux-toolkit.js.org : the Redux Toolkit docs. Has extensive API docs for RTK and RTK Query, as well as usage guides for both RTK and RTKQ

Each of those docs sites is built out of content in their respective repos.

The RTK docs did have a set of "basic/intermediate/advanced" tutorial pages in 2019. However, when I rewrote the Redux core docs tutorials in 2020, I realized that A) the new tutorials were much better, and B) having duplicated tutorial content was confusing.

So, the approach I settled on was that all the actual "tutorial" content would go in the core docs site, along with the general-purpose usage guides (testing, thunks/selectors, etc).

API docs and usage guides for the specific libraries would stay in their separate repos / docs sites.

I've thought about the idea of consolidating all the docs into one large site. There are some potential benefits to doing so, including only having one place to find things.

BUT...

in order to do that, we'd almost definitely have to merge all three libraries into a single merged monorepo.

That would be a massive undertaking. We'd have to:

• Rewrite the Git history to take, say, https://github.com/reduxjs/react-redux/tree/master/src , and move that to /packages/react-redux/src, and pull that history into a combined repo
• Then we'd have to figure out how we're going to merge all the thousands of issues and discussions, and organize them
• And for that matter, even once you get past the technical issues of merging the repos and the libraries, then we'd have to figure out what a heavily revised and combined docs structure would look like

To be honest, we simply don't have time for any of that. The Redux team is basically 2.75 people at this point: me, @phryneas , part of @msutkowski's time, and @timdorr quietly keeping an eye on things in the background. We've all got full-time jobs, and actual lives beyond that. (well. sorta, anyway :) )

As it is, the current main focus of getting RTK 1.9 out the door has been taking months. Lenz hasn't had much time recently, and I've managed to put in a few focused evenings to pick off some tasks, but that's taking way longer than I wanted it to. And after that, we want to work on RTK 2.0.

So, even if we wanted to drastically revamp the repo and docs structure, we don't have the hundreds or thousands of hours of effort available to do that.

Given that, the current docs sites structure is going to stay for the foreseeable future. I agree that there can be some confusion due to the multiple sites and different locations for some of the info, but this is the best we can do atm.

[msutkowski]

I am actively working on conjuring time.

[greebl3]

Appreciate the quick responses. That totally makes sense - I'll contain future PRs to RTK as much as possible.

The only (unsolicited) suggestion I'd have is to replicate the RTK link (found in Getting Started with Redux - Installation, for example) on more pages and/or move it to a persistent banner/button. As it stands now, it's really easy for newcomers to miss it, and go down the rabbit hole of parsing the Core docs before it's truly necessary.

To be clear, I'm not expecting the main team to shift gears and start working on my pet peeves. But if this approach has your blessing(s), I'd include this in my own personal roadmap for contributions. It's too large of a suggestion to include in a single PR, so I figured I'd float the idea here.

Honestly, using RTK has been a real joy, so I'd be glad to PR + help smooth over any onboarding bumps for newcomers

[markerikson]

Hmm. I'm actually not quite sure what the "RTK link" suggestion is, or what you mean by "the rabbit hole of parsing the core docs". Can you clarify that?

The ideal sequence is that learners should go straight to the "Essentials" tutorial and go through it start to finish. Alternately, go through "Fundamentals" and then "Essentials".

We've also got the couple "Quick Start" pages for people who just want "give me a couple quick examples and I'll figure things out from there".

[markerikson]

Related issue for linking purposes: reduxjs/redux#3958

[markerikson]

Pasting some feedback from Discord:

Without putting together a detailed feed back doc, and again, this is at least just my opinion, I think the main hang-up I have is it feels like there is a disparity between going from "Quick Start" to "Usage Guide" as far as getting a sense of how to use RTK. The "Usage Guide" flow to me feels a bit like here is every possible thing you could know about this concept and not necessarily RTK itself.

Example being createEntityAdapter.

The docs flow with the normalizing section introduction Managing Normalized Data into "Normalizing by hand", "Normalizing with normalizr", then "Normalizing with createEntityAdapter", followed by "Using createEntityAdapterwith Normalization Libraries".

There is a lot of reading and information before the docs tell me what createEntityAdapteris and does. To me, it feels confusing in that it pulls away from what RTK is doing and that it's already normalizing data with createEntityAdapterI don't have to use normalizr or do anything by hand because createEntityAdapterhandles this, but that info just feels sandwiched in between everything else without emphasizing that RTK can be used with itself entirely in isolation.

Not sure if that's clear or not, so I'll try give an example flow.

What feels more intuitive to me is something like:

• createEntityAdapter— what is and it does (normalize data and provide the RTK state shape + generate reducers and selectors) and how to use it with the rest of RTK (Building on how RTK itself is all I need and how it works with itself only.)
• Why createEntityAdapterdoes what it does (why normalization is common and important)
• What normalizing by hand looks like
• What normalizing normalizr is like
• How to use preexisting normalization libs in conjunction with createEntityAdapter

I feel like the entire "Usage Guide" flows this way where the "RTK" parts are mixed in the middle of a bunch of other information that isn't RTK specific. My purpose in reading the RTK docs is because RTK is a solution to a problem and I want to know how to use it.

Analogy of informational logical flow:
If I ask someone a question, I'd expect them to provide an answer first and then explain why that is the answer and then conditions that may make that answer change. If I ask "What color is the sky?," I'm expecting something like "blue" and not an explanation of light wave lengths (why), then say it's blue (what), and then give me conditions of when it is not blue (more why and sort of how?)

So in this case, createEntityAdapteris the answer, the reason why it is the answer is because it handles normalization, and the conditions that change the answer are if I'm already using another solution for normalization, here is how I can use it in conjunction with createEntityAdapter.

also seems like lack of clarity around there being separate docs sites contributed to the confusion:

That may also be part of what leads to some confusion, at least on my part.

There is Redux, React-Redux, and RTK. When the general suggestion is RTK is the go to, I'm skipping over the idea that there 2 other docs sites that may have the information I'm actually looking for or the context needed to understand the RTK bits
I also appreciate pointing out the difference of the usage guide in general. I think I'm so used to just going to a usage guide for other docs because I already have a very rounded idea of what I'm doing with things that are objectively less complex than RTK. Bad heuristic in looking at documentation and expecting to grok something from something like a usage section

[markerikson]

A few other folks have recently complained that having multiple docs sites with partially overlapping and partially exclusive content can be confusing. (Especially folks who end up on redux-toolkit.js.org and think its mini-tutorials are the only Redux tutorials.)

I've done a bit of research, and it seems like it might be technically feasible to have one giant merged docs site that is built out of content from all 3 repos, which would involve cloning the RTK and RR repos into the Redux core docs build step.

There's a lot of potential technical complexity here:

• Would have to figure out how to manage the build step
• Would need to figure out a massive revamp of the docs structure and organization to accomodate all the different content
• Would need redirects from the other sites to the core site
• Not sure what the dev workflow and deployment process would look like for the RTK and RR repos if we do this

This is still a very low priority for me given all the other things we've got going on. Updating the tutorials and working on RTKQ features is still much more important. But I can at least envision a hypothetical way to build a combined site technically that wouldn't involve having to merge all 3 repos into a monorepo.

[greebl3]

Happy to see this thread continue to get attention - thanks for caring about this @markerikson

Just the other day, I was onboarding a team to RTK. Knowing “how” to read the docs played a huge part in communicating its value, especially compared to other state management tools that have cropped up recently. So there’s definitely still a need for this even if it isn't high priority.

As always, let me know how I (and anyone else, for that matter) can pitch in!

[markerikson]

@greebl3 yeah, if you or others have examples of specific issues with the current organization and/or suggestions on how to improve them, I'm definitely interested!

The most immediate thing would be someone putting together a working technical proof of concept for a merged docs build. The very first viability step would be a POC that shows pulling in one existing page from both the RTK and React-Redux docs, regardless of how those pages get organized or included. (In other words, I'm not looking for an ideal navigation layout or any permanent decision - just do something that involves cloning the other repos during the build step and including one piece of their content in the final core docs site).

fwiw @riqts has also expressed an interest in trying to help with that, but I'd be happy to see dueling PRs to get a sense of what's possible :)