[Docs Rewrite] Meta-Issue: Recipes section

[markerikson]

This is a tracking issue to cover all work related to rewriting the "Recipes" section.

Tasks

• Move "Configuring Your Store" to "RWU"
• Add store setup info to "Quick Start" / tutorials
• Drop / move "Object Spread" to "Understanding" > Concepts > Immutability" ?
• Drop "Using Immutable.js" ( [Docs Rewrite] Remove "Using Immutable.js" page #4052 )
• Rethink "Reducing Boilerplate"
• Rewrite / improve "Testing" (Improve documentation on unit testing redux components #1462)
• Improve "Usage with Typescript"
• Improve "Server Rendering" (Update the Server Rendering guide due to the changes in the Counter example #2211)
• "Structuring Reducers"
  • Drop / rework "Refactoring Reducers Example" ("Refactoring Reducers" recipe shouldn't promote over-abstraction #3173)
  • Move "Prerequisite Concepts" to "Understanding > Concepts"
  • Move other content to "RWU" or "Guides" somewhere
  • Move "Initializing State" somewhere better?

[markerikson]

While there wasn't a specific issue for it, I wound up making some major updates to the "Usage with TypeScript" page in #3633 after having finished merging in the new React-Redux "Static Typing" page.

[JustFly1984]

I would consider immutable.js as dead project. @leebayron does not respond to issues and PR since long time ago, and there is no maintainers, and a lot of bugs. I've replaced immutable.js with immer, and I'm very happy about it, except it has no structural sharing :/ Also I had a lot of issues with Typescript integration, and I consider immutable.js exhaustingly developer unfriendly.

[markerikson]

Yeah, we now explicitly recommend use of Immer (plus RTK), and I've recommended against using Immutable.js for years.

I'm inclined to drop that page entirely, and just have a small section in an "Immutability" page that says "You can use it if you want, but we don't specifically support or encourage using it".

[markerikson]

Having said that, I just looked at the analytics. Since June 1, we've had 627K hits to /, and 589K hits to "Getting Started". The "Using Immutable.js" page has 27K hits. That's only like 0.44% of traffic, but it is a rather non-zero number.

Still, I don't see a reason to keep it around long-term. Maybe we can link to the existing Markdown page in the repo if folks want to read it in more detail, for historical interest.

[joshribakoff]

+1 for not endorsing immutable.js, its a great lib I'm sure, but I've seen that it confuses newcomers who don't understand the difference between writing reducers to be immutable, and using persistent data structures to do so. Some people incorrectly conclude that you must use immutable.js to have "proper" immutable code.

[DzhideX]

This sounds simple enough:

Move "Configuring Your Store" to "RWU"

Though I don't understand what "RWU" is supposed to mean. The closest thing I can find is the real-world folder under redux/examples. Any guidance?

If this is indeed more complicated than it sounds then I'm open for suggestions!

[markerikson]

That's short for the notional new "Real World Usage" category.

For more details, see the extended "how I want to reorganize everything" comment here:

#3313 (comment)

I'm also debating calling it the "Usage Guide" category instead.

Note that any page renames / moving will require also setting up Netlify redirects in the website/_redirects file, so that old external links will get redirected to the new page URLs.

[emgoto]

Hi! What could I help out with from here?

[markerikson]

@emgoto Appreciate you volunteering to help :)

Tell you what. How about going back to my original notes on the docs rewrite at #3313 (comment) , see what I actually wrote there about the RWU section, pull that in here, and let's see if we can come up with a more specific plan for how we want to organize this stuff. I'm thinking we'd probably want some sub-categories in here, like maybe "Setup" would contain "Configuring Your Store", "Usage with TS", etc, but not sure on details yet.

Related: I'm not 100% sure I actually want to stick with the name "Real World Usage". Right now, the React-Redux docs have a "Using React-Redux" section (/using-react-redux/), and the Redux Toolkit docs have "Using Redux Toolkit" (/usage/). "Real World Usage" might be okay, but I'm wondering if maybe just "Usage Guides" would be better?

[nickmccurdy]

It would be nice to migrate the recipes to hooks as well (I updated the testing one in #3876). Would a separate issue be better or would you like to add it to this list?