[Docs] Considerations for potentially merging all our docs into a unified docs site

[markerikson]

Background

Copy-pasting my comment from reduxjs/redux-toolkit#2637 (comment) (and also similar thoughts in https://www.reddit.com/r/reduxjs/comments/1e4r3ts/the_worst_documentation_ever/ ):

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 there isn't active development work going on atm.
• 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

(You could also include Reselect as well, which now has its own site too.)

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

---

An alternative approach would be to do something purely CI-based. Keep the three separate repos with their separate docs content, but have the core docs site clone the other two repos in CI and combine the content into a single merged site.

This is also doable, but would again take significant amounts of effort to pull together.

Other Prior Discussion

There's several other related comments and thoughts in:

• Meta-question: Onboarding through documentation redux-toolkit#2637

Considerations

Off the top of my head, and wearing my Project Manager hat, there's multiple aspects we'd need to plan / prototype through to know how this would work:

• Build / Deploy:
  • overall approach (extract all content to a separate repo? keep repos, but core site pulls others in CI?)
  • how does our docs-writing workflow change, especially in associate with feature PRs?
• Content:
  • What pages are duplicate? What can go away?
  • What does the merged site look like structurally? What about navigation (sidebars, headers)?
  • what does the new URL structure look like?
  • We have numerous cross-links across the sites. All those would need to be updated
  • I'm sure there's other aspects that would need to be updated here
• Migration
  • How do we turn off the old docs sites?
  • How do we handle appropriate redirects from the old sites to specific pages on the new site?

Beyond that, there's the larger questions of "how long do we think this will take?", "how much benefit will users get?", and "is this a higher priority than working on actual features and bug fixes?".

[timdorr]

We could move the website to its own repo for clarity. That's what we do on React Router: https://github.com/remix-run/react-router-website

[markerikson]

Yeah, that's the third option. I'd prefer not to do that, to try to make it easier to keep the docs and code in sync, but it's a possibility.

[timdorr]

Under the separate repo option, I would still keep the docs in their respective repos, but load them into the docs site repo during its build process.