[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