Discussion: revamped docs content, structure, and teaching flow

[markerikson]

Per discussion in #2590 , we'd like to rethink the Redux docs content and structure pretty much from the ground up. Now that we've got the new docs site up and running, it's time to start brainstorming what that content should look like. (There's already a bunch of discussion and notes in #2590, but I wanted to open a new issue specifically to brainstorm ideas.)

There's a few questions that we should try to answer:

• What specific topics should we try to cover in the docs?
• What should the new user reading flow look like?
• How should we organize the content?
• How do we approach teaching Redux?
• How do we integrate teaching and encouraging the use of redux-starter-kit into the new docs?
• What are the weaknesses and deficiencies in the current docs that we are trying to resolve?
• How do we handle teaching prerequisite concepts like immutability, JS array methods, and event emitters, in relation to the actual Redux concepts and usage? How do we differentiate between teaching "plain" Redux usage, and usage with a UI layer like React-Redux?

In general, there's lots of good Redux tutorials, articles, and resources out there. I would like us to beg, borrow, and steal the best ideas and examples out there for use with the docs (with permission if appropriate, of course :) )

Anyone is welcome to contribute to this discussion, but I'd particularly like to get involvement from other people who have experience writing material that teaches Redux or working on docs. On that note, tagging:

@dceddia
@rwieruch
@joshwcomeau
@valentinogagliardi
@alexkrolick
@matthew-gerstman
@tylermcginnis
@gaearon
@timdorr

[matthew-gerstman]

How should we organize the content?
What are the weaknesses and deficiencies in the current docs that we are trying to resolve?

IMO organization is the problem we're trying to solve here. We have a lot of content and its hard to find/parse. Here's a rough outline similar to the one @alexkrolick did in the previous thread.

Outline

Landing Page (Readme)

We should be optimizing here for not scaring the user. I don't think we should be using the docs to sell redux, chances are the reader has already opted into it by default.

This should cover a basic what is redux and how to install it. We should then push the user to one of the major sections I'll outline below.

Getting Started Guide

• As short as possible guide to writing your first react + redux app. This should have light definitions of things for example, actions/reducers, but rely on the API Reference as a place we can link out to.

• After we give the user working code (really what they came here for) we should have a "thinking in redux" subsection. This should push users to think about Redux the way we want them to.

Api Reference

This should feel like a reference textbook. Lots of definitions, explanations of how to use the store etc.

Integrations

Typescript, Vue, ReasonML, SSR, whatever else people are using redux with.

Other questions

How do we handle teaching prerequisite concepts like immutability, JS array methods, and event emitters, in relation to the actual Redux concepts and usage?

I think these should be things we mention in the getting started section and then link out to in the API reference section.

How do we differentiate between teaching "plain" Redux usage, and usage with a UI layer like React-Redux?

Do we really want to encourage plain redux usage anymore? Do we have any kind of stats on how many people still do this? I also feel like people who want to roll their own redux integration will be mostly focused on the API spec.

How do we integrate teaching and encouraging the use of redux-starter-kit into the new docs?

We could decide that redux-starter-kit is the fastest way to get the user through the getting started guide. If we do that we start teaching the starter kit instead of redux core.

[markerikson]

Do we really want to encourage plain redux usage anymore?

Not "encourage", exactly, but I think there's definitely value in teaching people what the bare-bones "by hand" usage looks like, so they understand what's happening. That way the later abstractions will make more sense.

As part of that, much of what RSK does only really makes sense once you understand the annoyances of doing everything "the hard way":

• configureStore simplifies the dance around middleware setup, composing enhancers, etc
• createReducer lets you avoid switch statements (which apparently is a big deal to many people), and supplies the "magic" in the form of automatically using Immer, thus allowing you to drastically simplify reducers
• createSlice generates action types and action creators for you so you don't have to write them by hand

But those are all abstractions that really benefit from the user understanding what doing it by hand looks like, so they know what's going on. Quoting Dan:

Dan Abramov, just now : "if you want to teach someone why to use an abstraction, you should first make them feel the pain of not having it"

[matthew-gerstman]

Just wanna clarify here.

When I said bare-bones I mean redux without react-redux, redux-starter-kit etc. I'm thinking manually calling subscribe etc.

I think we should be pushing some level of abstraction by default. That could be either react-redux or RSK.

To nitpick on Dan's quote. I don't think we need to teach the "why" right away.

I want to give readers a sense of accomplishment (by using abstractions) as quickly as possible and then push them to learn underlying concepts (pub/sub, immutability, etc).

[markerikson]

Right, so the over-arching question here is, how do we structure the content based on that?

Also note that React-Redux and RSK aren't mutually exclusive - RSK is just about the "Redux usage" level, and thus useful no matter what UI layer you're using.

[matthew-gerstman]

• Landing Page (Readme)
  • Getting Started Guide
  • Api Reference
  • Integrations

Does this basic outline seem reasonable? I kind of think of it like the user is gonna do a depth first search on the docs so getting started should be light and then the other two can go much deeper.

[markerikson]

My Thoughts

I'm gonna toss out my initial thoughts off the top of my head, without doing further in-depth analysis and comparison with other approaches.

In general:

• I want to restructure the pages and material so that there's some clearly defined "paths" based on your skill level and what you are hoping to learn
• I want to explain how all the pieces work from the ground up, but I also want to show "optimal" ways to do things too (particularly redux-starter-kit). I'm not yet clear on how to best teach both of these aspects.
• I want to emphasize "how to use this", and separate out some of the "why it works this way" material (particularly looking at the "Middleware" page here)
• I really want to add a lot of material around real-world usage patterns, including side effects, app structure, etc
• We should add CodeSandbox embeds and diagrams everywhere
• Pages should link to additional material at the end wherever possible

Thoughts on Current Sections

Landing Page

Right now we've got a giant "Get Started" button, and the top bar links set points to "Getting Started", "API", "FAQ", Github repo, and the "Need Help?" section of "Getting Started".

We've also got the "sales pitch" paragraphs + icons, links to React Redux and Redux Starter Kit, and (for now) the docs revamp survey.

I'd really like to have some kind of "guided path" links here, like:

I want to:

• Try Redux for the first time
• Learn through tutorials
• Understand how to "think in Redux"
• Learn best practices for real-world usage

These might link directly to specific pages, or they might point to an intermediate page that further links to "Read pages A, K, and Q, in that order". (Examples: https://twitter.com/jaaaarwr/status/1079570766742675456 , https://metacademy.org/ )

Introduction

"Getting Started", "Installation", and "Examples" are probably okay as-is, and probably keep "Learning Resources" here too. "Motivation", "Three Principles", and "Prior Art" should probably be moved into the new "Thinking in Redux" category. "Ecosystem" should be moved under the new "Real World Usage" category. We should add a new "Quick Start" page that shows fast app setup using RSK and React Redux.

Tutorials

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

Recipes

Oh, dear. This section has become such a hodgepodge of random stuff. A lot of the content in here is good, but needs to be moved to other sections, primarily a new "Real World Usage" section, and possibly a new "Guides" section.

Thoughts on some specific pages:

• "Configuring Your Store": moved to "RWU", but should also re-cover this in the "Quick Start" page and some of the tutorials
• "Object Spread Operator": goes away, mostly subsumed by "Prerequisites > Immutability"
• "Using Immutable.js with Redux": I'm not entirely happy with this page overall. It was contributed by someone who's a big Immutable.js fan. Don't want to just pitch it, but I'd like to downplay Immutable.js overall. Maybe under "Guides" or "Advanced" ?
• "Reducing Boilerplate": some good content here, but I feel like it's mostly ignored. Could maybe be split up into other pages?
• "Structuring Reducers": I wrote this, so it's kind of my baby :) Could use some rethinking, though. I know Dan isn't keen on the "Refactoring Reducers Example" page (per "Refactoring Reducers" recipe shouldn't promote over-abstraction #3173). Probably moved under "Guides" or "Real World Usage". The "Prerequisite Concepts" page should be moved out into a series of separate pages in the new "Understanding Redux" top-level category.

FAQ

Again, I wrote this, so I'm rather proud of it (and have heard lots of good comments about it). Main thoughts here:

• We should look at the FAQ entries, and try to figure out how to also show as much of that info in other pages too, so that people can learn the info as they go along through the docs.
• Probably worth reviewing the links for each entry, cleaning up any dead links, and trying to highlight the the top 2-3 additional resources for each question (like Dan's Stack Overflow answers for the "Why use middleware for async?" question).
• We probably ought to add a "How does Redux compare to other state management solutions?" entry (MobX, GraphQL, Context, etc). Or maybe its own page.

Other

The "Feedback" page should go away. I didn't even think I included it in the new docs page. We never used the Product Pains site in any meaningful way. At most, it should point to the issues list, SO, Reactiflux, etc.

There's overlap between "Troubleshooting" and "FAQ" that we ought to think through.

Ideas for New Sections

Real World Usage

This should be the biggest improvement to the revamped docs: lots of guidance on how to correctly structure a meaningful Redux app. This is the biggest area we don't cover well right now. Large portions of this could be existing material that's moved around, but we definitely need to cover things like:

• Side effects (comparisons of different approaches, how to choose a side effects lib, etc)
• Debugging
• Static types
• Selectors
• Using middleware effectively (including writing custom middleware)
• Folder+file structures
• Use of redux-starter-kit
• Working with the Redux ecosystem

Should probably also have some "advanced usage" sections in here, like store enhancers, batching subscription notifications, etc.

Using Redux with a UI

This section should start with a page that talks about the basic update sequence (subscribe, get state, update UI), and show how to do it in vanilla JS. It should then have multiple pages that talk about how to use Redux with each major UI framework (React, Angular, Vue, Ember).

Understanding Redux

This section has several objectives:

• Teach the "prerequisites" needed for Redux, including JS array methods, immutability, etc
• Teach people how to "think in Redux" (multiple reducers listening to one action, treating actions more as events than "setters", etc)
• Some details on how Redux works internally
• Info on when you should use Redux, and why Redux patterns exist. (This should mostly be cribbed from Dan's "You Might Not Need Redux", my "Idiomatic Redux: The Tao of Redux" posts, and Justin Falcone's "What's So Great About Redux?").

Style Guide

This is a direct ripoff inspiration from the Vue.js Style Guide page. The goal here is to actually express opinions on what we think are good approaches, but also qualify how strongly we feel about each one. Items off the top of my head:

• Folder structure: "feature folders"
• Use POJOs, not Immutable.js
• Use Immer for reducers (and even better, RSK)
• Start with thunks, add sagas or observables later
• Write actions as "events", not "setters"
• Write more logic in reducers, rather than calculating the new state on the action dispatching side
• Avoid "blind spread" reducers as much as possible
• Write actions that have semantic meaning when reading the types

Suggested Revised Structure

With all that in mind, here's a sketch of what the new docs structure might look like (with handwaving of the exact individual sub-pages):

• Introduction
  • Getting Started with Redux
  • Installation
  • Quick Start
  • Examples
  • Learning Paths / How to Read the Docs
  • Additional Learning Resources
• Tutorials
  • Intro
  • Basic
    • Actions, reducers, hand-subscribing, connecting
  • Standard
    • middleware, thunks, AJAX calls, selectors, RSK
  • Real World
    • stuff
• Understanding Redux
  • Prerequisite Concepts
    • JS Array methods (particularly with an emphasis on .reduce())
    • Immutability
  • Why Does Redux Work This Way?
    • History: Flux
    • Prior Art
    • Reasons for actions, immutability, reducers, etc
  • How Does Redux Work Internally?
    • Various internals explanations (createStore, applyMiddleware, why middleware are implemented this way)
• Using Redux with a UI
  • Basic Process / Vanilla JS
  • React
  • Angular
  • Vue
  • Ember
  • Other (?)
• Real World Usage
  • Configuring Your Store
  • Code Structure
  • Style Guide
  • all the other stuff I've talked about
• FAQ
  • same FAQ pages
• API Reference
  • same API reference pages

Other Thoughts

Looking at Vue's docs specifically, they don't have everything all in one giant TOC list. There's separate TOCs for "Guide", "API", "Style Guide", "Examples", and "Cookbook". Have to say it's not immediately discoverable - those are listed in a hover menu labeled "Learn" in the header. There's another hover menu labeled "Ecosystem" that has "Help", "Tooling", "Core Libs", "News", and "Resource Lists". Not sure if that's something we would want to emulate, or even if it's possible with Docusaurus.

We've already got a lot of content, and we're looking at adding a lot more. I'm concerned about how big the TOC is going to get, and how people will find the info they need. Docusaurus doesn't currently let us minimize TOC sections by default, but there's a PR. Is that something we'd want to use?

I want to get involvement from other Redux tutorial authors, both for ideas and actual content as well.

I've bookmarked a bunch of articles on how to write good documentation. I need to actually read through those and try to pull out some lessons. We should also spend some time going over docs sites for other libs and see what useful techniques we can pull out.

I can't do this all myself - gonna need a lot of assistance :)

Finally, I've been running a survey asking for feedback on the current docs structure, and suggestions for improvement. We're currently at about 100 responses, although I tweaked the questions after the first 75 or so. I'm attaching a PDF with a printed version of the summarized responses, and a spreadsheet with the actual responses:

Redux docs improvements survey responses.pdf

Google Sheets: Redux Docs Redesign Survey (Responses)

[wgao19]

Hope to contribute here too :)

I'm a fan of small, concise, well-organized official docs.

Suggest smaller docs, more guides > tutorials, more intentions with examples

• If the official doc explains things well and brief, people won't have to consult too many other learning materials.
• Seasoned developers know exactly what they need to know, so we should navigate well for them.
• For learning developers (myself). I learn fastest by getting my hands dirty and digging into source code. Again I prefer to consult less literature.
• But at the end of the day I really want to know whether I'm using it in its intended way. I think this is something I could not have figured out by myself. It is rather subjective and based on experience.

So based on @markerikson 's suggested outline, can I suggest to combine "tutorials", "real-world" (tutorials have a "real-world" section too), "using with UI" to a "usage" section. And instead of making them tutorial like, make them more "guide" like?

Another reason I wish to reduce "tutorials" in favor of "guides" is that there are a lot of podcast-based tutorials that might actually work better than docs. Dan's Redux course is free on egghead.io.

Suggested Outlines

(omitting the subsections)

• Intro
• Usage
• Understanding Redux
• FAQ
• API References

And the "Usage" section, in particular, can have the following subsections:

• Usage
  • Basic: Actions, reducers, subscriptions, selectors
  • Using with a UI / connecting
  • Middleware: thunks, sagas, writing your own middleware, etc
  • Real World Usage / Good Practices
    • Configuring Your Store
    • Code Structure
    • Code splitting
    • Style Guide

I feel every single section under "real world usage" has tremendous value to address.

"Configuring store", for example, gets complex when using Redux with other libraries such as React-Router, Rehydrate, other middleware libraries, etc. In real life we connect quite a number of libraries. That file is a bit hairy. (It's very hairy, in fact 😅)

Each library most often includes guide on using Redux with just that library. Sitting in the center of this issue perhaps we should provide a guide on configuring Redux with all of those libraries.

More Real CodeSandboxes in "Real World Usage"

Like I mentioned earlier I think how it is intended to be used is valuable. And I think the official doc is very responsible to educating its intended usage.

Can we have more "real" examples to showcase good practices?

Can we possibly ask people to contribute by "donating" real usages, i.e. submitting link to a CodeSandbox that recreates the usages in their apps?

FAQ

I'd really love to have your "Blogged Answers series" here: i.e., answered questions turned into doc page. I'd like to help work on those too. Although, I think it'd work better if we encourage the people who asked the questions to write those pages.

[timdorr]

I think the only problem I see is there are like 5 different starting points for the docs. "Introduction", "Getting Started", "Quick Start", "Installation", "Intro", "Examples". Those all pop out at me, so I don't know which one to click on first. I believe those can be combined in some way. In particular, it's always irked me that we have a separate installation guide. That should just go in the Getting Started guide.

[matthew-gerstman]

As I think more on this I think we're missing some important data from the community about how Redux is used. I propose we put out a lightweight google form and try and get some responses.

@markerikson @timdorr If you like this idea I'll add you as owners of the doc

https://goo.gl/forms/POkWwcwnuk9HiPo12

[matthew-gerstman]

Just putting this all in one place. Here are all the polls @markerikson has run over the past 6ish weeks plus one retweeted from @gaearon

https://twitter.com/acemarke/status/1084245223226650624
https://twitter.com/acemarke/status/1083915904893808640
https://twitter.com/acemarke/status/1083767611299639296
https://twitter.com/acemarke/status/1086798115812843520
https://twitter.com/acemarke/status/1086748345513766912
https://twitter.com/dan_abramov/status/1083188821150322689
https://twitter.com/acemarke/status/1078332610609401856
https://twitter.com/acemarke/status/1069806552071266304

[markerikson]

Haha, thanks :)

[markerikson]

I've referenced the Vue docs already, but we should also specifically look at the NgRx docs for some comparison as well: https://ngrx.io/guide/store

[Nimelrian]

Chiming in since Mark has asked for more feedback over on Reactiflux.

Disclaimer and Preface

I'll disclaim beforehand that I have not used the docs for almost 2 years now, mainly because Redux's API is so small that it's easy to learn it by heart.

I'll also preface my comments with stating that I'm one of those devs who argue that people should learn the basics of a language and its standard library before heading towards more complex topics. This is especially evident with the JavaScript community, where people often run into problems because they don't understand the language they're working with and dive straight into UI development. As such, I would expect someone who wants to start using Redux to have a general understanding of JS.

An inexperienced dev diving straight into advanced topics causes frustration on two sides:

1. The rookie becomes frustrated because they run into errors without knowing what causes them
2. The more experienced devs who have to deal with the rookie's subsequent questions about basic topics, which the rookie could answer themselves if they would have started at a more suitable point on the learning curve.

Current Docs

Now, for my actual comments for the current docs, so I can establish a foundation to base my arguments regarding the revamped docs on:

• Skimming through the current docs, it seems that a lot of the content is about teaching basic principles of immutability, control delegation and the application of these patterns using Redux.

• React is mentioned way too early and is actually used as an example for composition about one third into the Getting Started page. I dislike this. Even though Redux is often used together with React, the docs should move any mention of it into a later section.

• The Getting Started page throws tons of links at the reader. It is almost ironic this is done in the "Just the Basics" section. This is an unnecessary information overload.

• The noise-to-signal ratio on the Reducers page is way too high. If I have the docs open on one screen and a code editor on another to type along, I easily get lost when taking my eyes off the editor and trying to find where exactly in the docs I left off. This is bad. It gets even worse when a reader is working on a laptop and only has one screen at his disposal. On a 1080p screen, there are multiple instances where a code block is covering the whole screen. This causes the reader to lose sight of what the code he's reading is about.

• The "Usage with React" and "Example: Todo List" pages are using prop types. They are, imho,de-facto deprecated by now. The examples are small enough that type validation shouldn't be needed here. In real world apps, people usually resort to Typescript (or Flow) nowadays anyway... At least they should. Some people are just stubborn and/or masochistic.

• In general, the docs feel like a giant wall of text and code.

Revamped Docs

• Add graphics. They fluff things up while conveying basic principles (or help understand them).

• Reduce the complexity of the code samples when explaining actions, reducers, etc. Do not use the todo app as the source for this. Even with the inherent verbosity of Redux, we should strive not to fill a 1080p screen with a single code sample.

• Move any mention of React out of the basic tutorials. Encourage people to start with a simple node application for the basic tutorials. Focus on the important, not on the eventual goal.

• Preface the docs by stating that a previous knowledge of the concepts of immutability and control/slice delegation is recommended. The docs shouldn't refrain from using a quick reminder on what each of these concepts does, but they should not be explained from the ground up.

• This one is going to be controversial: Use Typescript. Even in the docs. Redux is about making the state of big applications maintainable and predictable. Type checking makes this even easier.

• Move links with more information to a "Further reading" section. We shouldn't point the reader to other sources to learn the stuff we want to teach him ourselves.

• Regarding async actions: Remove the mention of the Fetch API. Use a dummy API object with some methods returning promises and use redux-thunk's thunk.withExtraArgument. This also helps to avoid mocking the Fetch API in the testing section and teaches clean code via dependency injection.

That's it from me so far :)

[matthew-gerstman]

I'd really like to get started on actually writing so I'm going to propose some process 😱

1. Let's agree on an outline. @markerikson and @timdorr I imagine you two have the final say here. My vote is Mark's proposal.
2. Open a new branch and setup the TOC. Let's just get page headers for everything we want.
3. Allow the community to write the bulk of the content and code samples. Pull requests should be submitted to the branch from Spelling fix #2.
4. Copyedit so it sounds like it's coming from one voice.

Anything I'm missing? @markerikson @timdorr can we get some kind of kickoff? I'm happy to contribute a lot to #3, but I'm not comfortable kicking off the TOC.