[Docs Rewrite] Meta-Issue: Tutorials

[markerikson]

This is a tracking issue to cover all tasks related to rewriting and updating the "Tutorials" section.

Tasks

• Define goals and outline for new tutorial sequence (refs: General docs review, consideration, and improvements #2590 , Discussion: revamped docs content, structure, and teaching flow #3313 , Tutorial needs to focus, too scattered and difficult to get started #2933)
• Come up with better sample apps for tutorials
• Restructure docs sidebar: add "Tutorials" category, move "Basic" and "Advanced" under that
• Add "Barebones" tutorial
• Rewrite "Basic" tutorial
  • Rewrite "Usage with React" page completely
• Renamed "Advanced" to "Standard" and rewrite
  • Move "Middleware" page to "Thinking in Redux > Design"
• Add "Real World" tutorial
• Add a "Next Steps" page (Write the "Next Steps" docs page #2626)

[markerikson]

I was just browsing the analytics for the Redux docs. Here's the top 10 pages for the last week in pageviews:

1. /: 27.6K
2. Getting Started: 25.9K
3. Actions: 17.1K
4. Reducers: 15.5K
5. Usage w/ React: 14.7K
6. Style Guide: 12.8K
7. Tutorial: 12.1K
8. Example: 8.7K
9. Async Actions: 8.5K
10. Store API: 8.1K

So, this tells me that we've got a lot of folks actively learning React, and we should prioritize rewriting the tutorials. (And, that we need to get the tutorials right.)

Before we can do that, we need to have an idea how we're going to rewrite them.

Previous Thoughts

Here's my prior thoughts from #3313 :

I want to have a series of tutorials that add increasing levels of complexity. These might be based on or tied into the existing projects in the "examples" folder. The exact project types and implementations should be carefully thought out to help get across the specific concepts we want to teach for each one.

I'd like to keep these tutorials as focused as possible. That means skipping stuff like "three-phase actions", writing action constants inline instead of as separate variables and files, etc. I also want to start with as much stuff in a single file to begin with, and only split it into multiple files later, at which point I want to use "feature folders" instead of "folder-by-type". I also want to hold off on showing action creators right away. (Related: I ran a Twitter poll on what folder structure the tutorials and examples should show by default.)

Possible sequence:

• Barebones
  • Goal: show the absolute basic mechanics of the store API, no other libs or anything
  • Could use the counter-vanilla example for this
• Basic
  • Goal: show use of combineReducers, putting data in actions, immutable update logic for objects and arrays
  • I'd like to start off by showing hand-written subscriptions to Redux in React components, to build on the subscription usage in the "barebones" tutorial and prep for usage of React Redux
  • After we've shown that, then we can show usage of connect. However, I'd like to drop almost all the "presentational / container" terminology from this page and keep it focused on the bare basics.
  • Overall, this is probably mostly a modest rework of the existing basic tutorial to clean it up, than something entirely new
• Standard Usage
  • Goal: show "typical usage" of Redux and React Redux, including middleware, thunks, action creators, selectors, normalization, and debugging
  • Note: not calling this one "advanced", because it shouldn't be
  • Would want to focus on setting up and using these things and some info on why they exist, but without going into all the nuances of how they work (looking at you, "Middleware" page).
  • Would also really want to start finding places to demonstrate the idea of multiple reducers listening to the same actions.
  • After adding all these new pieces, I think this would be a good place to introduce Redux Starter Kit, and refactor the existing code from this tutorial to use RSK
• Real World
  • Goal: show the process of setting up and organizing a larger app than the current > "Reddit API" example
  • Should probably include routing, request success/failure cases and loading state, > and whatever else we can add in
  • Could consider holding off on the normalization and debugging parts until this tutorial

Discussion Points and Questions

• What specific points do we want to teach in each of the tutorials?
• How can we effectively teach both "this is how the lib works", "these are the related concepts you should understand", and "this is how to effectively use it"?
• How can we structure the tutorials to better engage learners, including giving them interactive ways to learn?
• What are better ideas for example projects than "a todo list" and "a Reddit post fetcher"? We somehow need ideas that demonstrate the mechanics of Redux, and yet don't get bogged down in a ton of overhead and distractions

[karimsa]

Hi! I’m a big fan of redux, first time contributor.

Personally, I absolutely love the style of gobyexample. What I often end up doing on documentation sites is skimming code and only reading the explanations if the code is unhelpful. To provide further context, there could always be a link to a jsfiddle/stackblitz/etc.

Though the depth of the current tutorials might be useful for some, it feels a bit daunting to have to go through 4-5 pages before being able to get started. So succinct examples that display something end to end would be super valuable.

——

Something to the effect of:

Creating a store

import { createStore } from 'redux'

export const store = createStore((todos = [], action) => {
	switch (action.type) {
		case 'ADD_TODO':
			return [...todos, action.todo]
		case 'REMOVE_TODO':
			return todos.filter(todo => {
				return todo !== action.todo
			})
		
		default:
			return todos
	}
})

// stateA = []
const stateA = store.getState()
store.dispatch({
	type: 'ADD_TODO',
	todo: 'my first todo',
})

// stateB = ['my first todo']
const stateB = store.getState()

// The two states are different objects,
// so this should be true:
// stateA !== stateB

Subscribing to changes

import { createStore } from 'redux'

export const store = createStore((todos = [], action) => {
	switch (action.type) {
		case 'ADD_TODO':
			return [...todos, action.todo]
		case 'REMOVE_TODO':
			return todos.filter(todo => {
				return todo !== action.todo
			})
		
		default:
			return todos
	}
})

store.subscribe(state => {
	console.log(state)
})

// Prints: ['my first todo']
store.dispatch({
	type: 'ADD_TODO',
	todo: 'my first todo',
})

// Prints: []
store.dispatch({
	type: 'REMOVE_TODO',
	todo: 'my first todo',
})

// Prints nothing, state doesn't change
store.dispatch({ type: 'foobar' })

[richardcrng]

I taught Redux to some React and JS novices in the past couple of weeks, and here are some rough initial thoughts/observations on an initial introductory sequence for the core concepts based both on what went well and what I wish I'd done differently:

• What is an action?
  • Including "what is the purpose of an action"
  • No payloads just yet, just type
• What is a reducer?
  • Emphasising repeatedly that reducers should return the new value of the whole state structure that they are responsible for
  • A common mistake seems to be "oh this bit of state should be updated" and only returning that slice of state
• What would be a sensible return value of this reducer (managing a number or array) when it is passed this state and this action? Now, how do we write it so that it produces that return value?
• What would be a sensible return value of this reducer (managing an object) when it is passed this state and this action? Now, how do we write it so that it produces that return value?
  • Probably using if statements up to the point of having perhaps 2/3 else ifs, and then introducing switch and case
• Oh, but we don't want to have multiple cases that do similar things (e.g. INCREMENT_BY_ONE, INCREMENT_BY_TWO). How can we get more information to our reducer? payload!
• Now I'm bored by having to write long object literals when I make similar calls to the reducer that only differ by payload. How can I make it easier? Action creators!

Then:

• Now we want something to keep track of state, so we're not having to hold something and pass it into our reducer each time. Let's create a store to keep track of state. How do we update its state? dispatching actions!

(This is obviously premised on teaching the core library first and not teaching first via RTK)

As we discussed on Reactiflux, @markerikson, if you think something like this would be of value, then I'd be happy to contribute some written tutorials for this sequence.

[zhaluza]

Hi, adding my thoughts as a Redux learner upon @markerikson 's suggestion.

After working with React for several months, I decided to try my hand at Redux. It took several separate attempts, but I finally had my lightbulb moment last week while working through the Redux half of The Net Ninja's React & Redux course (parts 34 onward).

Below I'll briefly explain my general path to learning Redux, including the resources I used.

I initially started with the main Redux.js site. Being self-taught, I looked for a resource that would walk me through the fundamentals of Redux, including the theory and how to implement it in an app.

Having no previous experience with Redux, I felt a little lost with the basic to-do list tutorial, so I jumped to the list of Redux resources.

I tried Dan Abramov's Egghead.io course, having heard a lot of people recommend it. While I was able to grasp the basic concepts discussed in the first few videos, I felt like I was missing a lot of the context I needed to truly grasp what was going on and where everything fit in. I was also having trouble understanding how I would apply Redux to the structure of a modern small-to-midsize React app.

I then watched Mark's "The Fundamentals of Redux" talk. This was really effective in teaching me the core concepts of Redux — how the store, reducers, actions, and provider work together to manage state across an app. For me, the next step was to apply it to an actual app.

I tried playing around with some of the example apps but had a hard time making the leap from knowing the core concepts to seeing the code implemented in an actual app and knowing how to do that.

The tutorial structure on the Redux.js site —building the actions, reducers, and stores in isolated environments, and then showing how it fits together in the end — didn't mesh with my personal style of learning. The video series linked at the top of this post worked for me because the instructor explained how the different parts of Redux worked while implementing them in a basic React app using a structure I was familiar with.

I'd be happy to clarify my explanation if any parts didn't make sense. Hope this feedback helps!

[markerikson]

A short article that says:

Redux is a very simple tool that is very poorly explained. In this article, I will explain Redux in a single sentence that is sorely missing from the Redux documentation.

Redux is a pattern for modifying state using events.

That’s it. It’s a dedicated event bus for managing application state.

http://evanxmerz.com/blog/index.php/2020/01/18/redux-explained-in-one-simple-sentence/

[markerikson]

Shorthand notes on the goals for redoing the existing tutorial sequence, since I keep pasting these in various places:

• Drop all outdated references ("Flux", "containers", etc)
• Show simpler patterns (inline action types like {type: "todos/addTodo"} vs const ADD_TODO = "ADD_TODO", single-file Redux logic)
• CodeSandbox examples
• Show React-Redux hooks
• Improve explanation flow

[albseb511]

Can I write a tutorial on how an over-simplified connect works with context api?
A lot of people can learn faster if they can make a simplified version on their own
Example
https://codesandbox.io/s/react-redux-9t5nj

Here is an example of using context API to get it done. ( i remember a gist from gaearon )
Its a comparison of how the API works.
I use this to teach to a lot of people, and they have been able to learn very easy after that.

I have some written docs for the tutorial, although its a rough draft.

@markerikson

[sbaudray]

For context: #3594 (comment)

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 reasoning behind my "choice" for the Basic tutorial was that I could learn how to write an action, without having to follow a long tutorial. It could as well be written with RTK.

Now after some looking around I understand that you want the documentation to focus on tutorials, while I am more of a "how-to guides" person as described in https://documentation.divio.com/

Besides, I've seen mentions of setting a "path" for the user. Getting something quickly setup with the "old way" before transforming the code to use RTK would make sense imo. They would gain a better understanding of what RTK does.

Maybe Essentials and (Basic + Advanced) should be split into "Modern" and "Classic" a la Relay to make the distinction clear.

Or maybe we don't need the distinction. It seems to me Essentials is already doing the job of Basics and Advanced. They could be merged.

I like your idea of Basics - Standard - Real World even though the line between Standard and Real World is really thin.
As a quick sketch:

• Basics
  • Core Concepts
  • Counter Example Barebone + RTK or one for each
• Standard
  • Social Media Feed Example
• Real world
  • SSR
  • Typescript

Real world would be the "RWU" section, acting more like the current recipes. It might not be realistic to put a real world application into a tutorial, this should be an example like https://github.com/reduxjs/examples/tree/master/real-world

I definitely lack a lot of insight so if I'm raising questions that are already answered please tell me.

[markerikson]

@sbaudray : Yeah, I think you're sorta over-analyzing what I'm looking for here :)

As described in #3855, the new "Essentials" tutorial focuses on "how to use Redux the modern way to build real-world apps using RTK", but doesn't cover the lower-level primitives and concepts that RTK is built on. The goal of the "Basics" tutorial is to explain those lower-level primitives. So, it's not so much about "modern" and "classic", but rather "higher-level abstraction" and "what those abstractions are abstracting".

I definitely don't intend to cover SSR in a tutorial. There may be some value in having a separate TS-specific tutorial in addition to the "Usage with TS" page, though, but definitely not including that in either the "Essentials" or "Basics" tutorials.

[markerikson]

The new "Redux Fundamentals" tutorial is now live! The "Fundamentals" tutorial teaches "how Redux works", from the ground up, and finishes by showing how Redux Toolkit simplifies the common Redux usage patterns:

https://redux.js.org/tutorials/fundamentals/part-1-overview

I'm going to declare that the actual work of rewriting the tutorials is complete, and close this issue.

However, just because it's been merged doesn't mean the content is immutable (😀 ). I'd love to hear additional feedback both from the people who commented in this thread and anyone else who might have thoughts on it.

In particular for the folks in this thread, does the new "Fundamentals" tutorial address the concerns and suggestions you've raised already?