[Docs Rewrite] Rewrite existing "Basic/Advanced" tutorial sequence

[markerikson]

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"} vs const 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)

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
• "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
• 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, and Immutable.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"

[markerikson]

Uh. Somehow I managed to open this issue, twice? That's lovely.

Closing this in favor of #3855 .