[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?

[sbaudray]

For the tutorial I will answer in #3594

Regarding the Core Concepts; it's my understanding that you want a tutorial centred documentation, so I would put them in the essentials where they basically already are.

[markerikson]

@sbaudray : I don't think I'd agree with the statement "you want a tutorial centered documentation".

Per the https://documentation.divio.com/ page you linked in the other issue (which is excellent and something I've already been referring to frequently), tutorials are part of a good set of docs. But, we also need references, usage guides, and explanations.

It's also worth having some of the same material in multiple places, so that people who might not look at a tutorial can still find it in an "explanation" area, etc.

The "Core Concepts" aspect is somewhere between "explanation" and "tutorial", conceptually.

[sbaudray]

I'm starting to get a better understanding of the direction :)

Shouldn't Core Concepts belong to Understanding Redux > Thinking in Redux, and we could link to it from the Basic tutorial ?

[markerikson]

@sbaudray : I'm actually wondering if we can combine the content from "Core Concepts" and "Three Principles" into a single page. If we did that, we could have ## Three Principles and ## Core Concepts as secondary headers. I'm just not sure what the combined page title should be.

[sbaudray]

Core Concepts:

Imagine your app’s state is described as a plain object.
This object is like a “model” except that there are no setters...To change something in the state, you need to dispatch an action.
Finally, to tie state and actions together, we write a function called a reducer.

Three Principles:

The global state of your application is stored in an object tree within a single store.
The only way to change the state is to emit an action, an object describing what happened.
To specify how the state tree is transformed by actions, you write pure reducers.

The structure is actually the same, do we need them under secondary headers ? Or could they share a common structure e.g:

• Core Concepts
  • State
    • definition and principles
  • Actions
  • Reducers

[markerikson]

If there's a good way to consolidate and rewrite this content into one page, I'm up for that.

[edudar]

One thing I want to bring here that is not related to the structure of the section, it's examples. To me, the problem manifests itself across all docs and tutorials but it gets an intro in "Core Concepts". There are multiple places where it's mentioned that actions in Redux are supposed to describe "what happened". The "Core Concepts" page itself states this rather clearly:

An action is a plain JavaScript object (notice how we don’t introduce any magic?) that describes what happened

However, right after that, it goes with examples that contradict the very thing that was just said: ADD_TODO, SET_VISIBILITY_FILTER, etc. None of these describe what happened. These are do-something commands and "glorified setters". I've seen effects of this in real-life projects where engineers following such examples think about actions as about commands. This leads to a logic pile-up in UI components with sequential dispatch calls that just tell the reducer what to do: set this, change that, clear this. I think README here goes in the right direction with its examples of 'counter/incremented' and 'counter/decremented' as at least an attempt of "what happened" style. The docs, however, use 'counter/increment' as a command again and so forth.

I think proper examples would promote a better understanding of "why redux" and "how to redux" and that it's not just a framework to change global variables in an implicit, non-direct way with 4 levels of abstraction for one set operation.

[markerikson]

@edudar thanks for the feedback. FWIW, that is actually one of the many pages that need to be rewritten to reflect these newer principles :)

That said, in a lot of ways "actions are events that describe what happened" is an ideal, and one that's admittedly difficult to wrap your mind around. That's part of why there were so many arguments in the early issues about "Is Redux CQRS? Is it Event Sourcing? Is it Flux?".

At some point I want to write a docs page about "how to mentally model actions" that would give some advice on this topic. To some extent I don't feel qualified to write that page :) but someone's gotta do it.

Unfortunately, there's a ton of other stuff that's higher priority atm, so that won't be happening any time soon.