Closed
Description
Overview
The existing Redux "Basics/Advanced" tutorial sequence desperately needs to be rewritten. While it's been useful for many people, the target audience of the Redux docs has changed considerably since Dan first put it together. At the time, Dan said:
So hard to write the new docs. Many different audiences to cater to.
Should make sense to: Flux beginners, FP people, FP people who don't get Flux, Flux people who don't get FP, normal JS people too
Flux people: "is this proper Flux?" FP people: "is this that weird thing called Flux?" Normal people: "why not Backbone"
Clearly, the audience today is very different.
Flaws with the Tutorial
Goals
My main goals here are:
- Drop all outdated references ("Flux", "containers", etc)
- Show simpler patterns (inline action types like
{type: "todos/addTodo"}
vsconst ADD_TODO = "ADD_TODO"
, single-file Redux logic) - CodeSandbox examples
- Show React-Redux hooks as the default
- Improve explanation flow
Existing Redux Tutorial Sequence Notes
Previous Personal Notes
- Commentary from the original "rewrite the docs" thread, pasted into the "tutorials" issue: [Docs Rewrite] Meta-Issue: Tutorials #3595 (comment)
Feedback
- Tutorial needs to focus, too scattered and difficult to get started · Issue #2933 · reduxjs/redux · GitHub
- Too many steps / backtracking
- Assumes you have experience with Flux
- Takes too long to write anything
- No environment setup
- Doesn't show what file is being edited
- "Squirrel!" distractions (links to other talks, tutorials, libraries)
- Remove "Redux itself is very simple" : reactjs
- "Core Concepts" page throws around terms too early
- Needs diagrams
- Data formatting is hard to read (put each object on one line)
- Remove phrases like "nothing magical about it"
- Is there a way around learning Redux? : reactjs
- Intro > Getting Started code block has many large comment blocks describing various optional approaches
- Vue docs do a great job of teaching one little bit at a time and then explaining variants later
Introduction
- "Getting Started": remove basic example?
- "Motivation / Core Concepts / Three Principles":
- content isn't bad, but should these get moved somewhere else?
-"Motivation" is a bit dated ("models", the "time to give up?" link)
- content isn't bad, but should these get moved somewhere else?
Basics
- URL currently
/basics
- should be/tutorials/something
Actions
- No background for why these matter at all
- Everyone's favorite
const ADD_TODO = 'ADD_TODO'
- "Actions are payloads that send data to the store"
- Confusing phrasing
- Haven't even talked about stores yet
- "Actions must have a
type
property that indicates the type of action being performed"- Should say something about "readable name that describes what happened in the app"
- "Types should be defined as string constants and moved into a separate module"
- delete
- "Note on Boilerplate"
- Remove / re-think
- "Structure of an action is up to you"
- Links to FSA page, but we ought to emphasize
payload
more
- Links to FSA page, but we ought to emphasize
- "Good idea to pass as little data in the action as possible"
- Good to say "pass
index
instead of the whole todo", but rephrase this somehow
- Good to say "pass
- Actions are jumping straight into doing "todo app"-related stuff, with no context for what we're building, why, what features, etc
- "Action creators"
- This is almost definitely being introduced too early
- Comparison to "traditional Flux"
- Use of "binding action creators"? Also, we're talking about
dispatch
and none of that's been mentioned yet - "Portable and easy to test"? Delete
- "Action creators can be async and have side effects, read this later, but don't skip ahead"
Reducers
- "Reducers specify how app state changes in response to actions sent to the store"
- We still haven't defined what a store is
- "Actions describe what happened" is good
- "Designing the state shape"
- should this concept come before the "actions" part?
- "Minimal representation of app state as an object" is good
- "Todo app", but we still never even said what we were building!
- "Keep all state in a single tree": bleh
- "Note on relationships":
- too complex for this level of a tutorial!
- Didn't define "normalized", links to
normalizr
instead of our own docs page
- "Handling Actions"
- "Pure" and "side effects" are never defined
- Clear example of initial state is good
- Remove "easy"
- Use of
Object.assign({}, state, arg)
: ew! - "Object spread proposal" should change
Object.assign()
warning (ES6? really?)- Note about "switches aren't boilerplate, dispatching actions is": remove this
- "Handling More Actions"
- Shows a bunch of array spreading and stuff, without explaining what it's doing
- References to
immutability-helper
,updeep
, andImmutable.js
- "Splitting Reducers"
- "Our code is rather verbose": well, yeah, when you write it that way!
- Good example of "reducer composition"
- Explanations around
combineReducers
/ imports / reducer naming are a bit confusing - Remove the "Note for ES6 Savvy Users"