[Docs Rewrite] Meta-Issue: Introduction section

[markerikson]

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

Tasks

• Move "Ecosystem" to "Real World Usage" section
• Add "Quick Start" page that shows fast app setup with RSK
• Move "Motivation", "Three Principles", and "Prior Art" to "Thinking in Redux" section (do we leave any of this content up front?)
• Add some kind of a "comparison with other tools / use cases" page

[bpas247]

I just have a couple quick questions regarding the action items for this:

Move "Ecosystem" to "Real World Usage" section

This would make the "Introduction" section pretty long, which might be more cumbersome for new users. The "Ecosystem" section has a lot of information that might not all be relevant for new users.

Add "Quick Start" page that shows fast app setup with RSK

Would we still want the "basic example" section? or would the "Quick Start" section replace that?

Move "Motivation", "Three Principles", and "Prior Art" to "Thinking in Redux" section

Would this new section go under the "Introduction" section? or would it be its own section altogether?

[markerikson]

@bpas247 : not quite sure what you mean by that. The point is to move "Ecosystem" out of the "Introduction" category (where it already is) and into a brand-new "Real World Usage" category (which currently does not exist).

I'm not sure whether it's worth keeping that tiny example directly in the "Getting Started" page. I do think there's a different intent between that example and what I picture for a "Quick Start". The "Basic Example" is supposed to show "here's the raw Redux API in its smallest form". The "Quick Start" page would be "copy and paste this code that uses Redux Toolkit as the fastest way to get something meaningful working, and you can learn the details of how it actually works later".

"Thinking in Redux" would be another brand-new top-level category, completely separate from "Introduction".

[bpas247]

The point is to move "Ecosystem" out of the "Introduction" category (where it already is) and into a brand-new "Real World Usage" category (which currently does not exist).

Okay, I was just confused since I thought you meant to move "Ecosystem" to the existing "Real World Usage" section, which is a sub-section of the "Learn Redux" section. Moving it into a new category makes more sense then.

[markerikson]

Per the idea of a "Quick Start" page, see the feedback I just pasted into #3592 (comment) .

[sbaudray]

I think this introduction section could be reworked.

Analysis

n.b: "I" will sometimes represent a new user.

Getting Started with Redux

Redux is a predictable state container for JavaScript apps.

If I don't know Redux, I don't know what it means.

Installation

I understand that you're promoting RTK but it feels weird that it comes before Redux. You install the toolkit, and then you're left with a package that you don't know how to use because it's actually a different library than the docs you're on.

Learn Redux

If I come to the documentation to learn Redux, I won't lose my time looking at a bunch of links that can lead anywhere. So I would be like "let's skip this section, I will keep reading the docs". And the next step is installation.

Installation

I already read this! Let's go to the next page.

Motivation

Good decision to move it, at this point I should already know why I want to use Redux.

Core Concepts

Knowing Redux I would expect to find those subsections: Store / State / Action / Reducer. Concepts need names.

Three Principles

This whole section announces principles that should be included in the core concepts.

• single source of truth -> Store
• read-only state -> State
• pure functions -> Reducer

Note the ending phrase for Core Concepts:

This is basically the whole idea of Redux.

And for Three principles:

That's it! Now you know what Redux is all about.

It is redundant.

Prior Art

Again good decision to move it, I basically don't care about prior art, I just wanna use Redux.

Learning Resources

I already saw a section on learning Redux. I wasn't interested. And now you give me a zillion more links?!

Ecosystem

Again, more links ?! What the hell are all those libraries. I got my toolkit! Isn't it enough ? I'd better find something simpler than Redux... At this point, I might close the tab and go after a simpler solution.

Examples

At last I can see how to use Redux. But I didn't learn how to use it. Yes I could have clicked one of a thousand links, but the docs should teach me.

About the sandboxes, I find them super slow to load, not a great experience.

Proposition

• What is Redux
  • Definition/TLDR of Motivation
  • What it looks like (basic example)
  • Comparison with other libraries could go there, be it just a link if it's too big
• Installation
• Core concepts
  • Store
  • State
  • Actions
  • Reducers
• Where to go next
  • Official Tutorial
  • Examples
  • Learning Resources
  • Getting help

I know what is Redux. I know the core concepts. I installed the library. Now what ? I can follow the official tutorial, I can look at some examples, I can look up some online resources or find help on discord and whatnot.

Examples should be moved into their own section.
Learning resources and Ecosystem should be moved into the "Real wold usage" mentioned here.

Aside : It's another topic but for the tutorials I would link to the basic tutorial. It's down to earth and show me how to code the core concepts I've learned about.

The Essentials one is ultra scary. It begins by what's basically the Introduction Section. And then it's so big that it is slow to load. I've read a ton of Redux content, but this one I'm not sure I would.

That's a big comment. I hope this feedback is valuable and that you understand I respect the work done. If you think some things could indeed be done, let me know.

[markerikson]

@sbaudray thanks, appreciate the feedback! I'll try to look through those suggestions in more detail shortly.

Per the "Essentials is scary" and "point to the basic tutorial" comments: I get where you're coming from, but I'll have to disagree there.

The goal of the "Essentials" tutorial is to teach people how to be productive with Redux Toolkit, which is now our recommended default syntax for writing Redux logic, with a focus on "here's how to use it" instead of "here's how it works inside". But, to do that, they do still need to know things like what "actions", "reducers", and "immutability" are. So, that first page provides a crash course in those terms so that the rest of the "write this code and it just works" content (hopefully) makes sense. Agreed that it's a lot to go through to start, but we have had a number of very positive comments about the "Essentials" tutorial overall.

The "Basics" tutorial, on the other hand is A) very low-level; B) currently very-out-of-date; C) really doesn't help you build anything practical. So I definitely don't want to point people to that now, and even after I get done rewriting it, I don't want to point to that as the default.

If you've got specific suggestions for how to shuffle or improve the "Essentials" content, I'm definitely interested, but it's going to stay as the default.

[markerikson]

A few other quick thoughts:

• I'd probably want to move "Learning Resources" and "Examples" underneath the "Tutorials" category
• Generally agree with restructuring the "Getting Started" page
• But Redux Toolkit needs to stay as the default
• Dan originally wrote that "Core Concepts" thing as an SO answer or Reddit comment or something. The original intent is to show that Redux is more of a set of principles and a pattern than a specific library. Agree that it could probably be merged with "3 Principles". Not sure where that content should go, though - part of a rewritten "Basics" tutorial? Somewhere else?