General docs review, consideration, and improvements

[markerikson]

The Redux docs are great, and I'm not just saying that because I wrote a couple large sections :) However, much of the content was written right at the beginning, and while there's always been tweaks and edits from people over time, it might be worth stepping back and reviewing how they work as a whole.

When Dan was writing the docs initially, he 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”

2+ years later, the situation is somewhat different. There really are no more "Flux beginners", at least in terms of people who have just gotten started with a "standard" Flux library. Instead, people are coming straight to Redux, including people with little actual React experience. There's also probably less Backbone background as well, and overall the "Flux Architecture" is pretty well known at this point.

Another consideration is learning approach. The current tutorial sections take a very "from first principles" approach. For example, the "Middleware" page walks through 6 different ways to implement middleware functionality in various hack-ish ways, iterating up to the actual middleware signature. That's great for some people, but maybe not for hours. Are there other ways we could present things that might help some people? Would a "Quick Start" section or something like that be useful?

I'm not proposing that we throw all the docs out and start over, but I think it's worth trying to review and rethink what we want to say and how we want to say it, similar to how Dan reworked the React docs recently-ish.

I don't have any specific suggestions right this minute, but I want to solicit feedback and suggestions for any topics that we don't cover, or ways to improve what we already cover.

[markerikson]

First suggestion, from @jaredpalmer : adding some info (possibly in the README?) talking about the "right tool for the job", and "philosophy" type stuff. (I don't remember all the details of our conversation, so please feel free to fill in your thoughts on that, Jared.)

[markerikson]

Another suggestion, from this tweet by @acdlite :

I love love love the React Router docs so much. Specifically how they focus on real world use cases, with copious code examples. Possibly my favorite docs site ever. We should copy the exact same design for React's docs.

I dislike docs that are overly didactic in their approach. Show me the code. Please spare me the Socratic exercise. There's a place for that, but put it below the fold. Or maybe just write some blog posts instead, or record a video series. (I want to clarify: I dislike didacticism when it's in place of comprehensive API documentation and practical code examples. Those are table stakes.)

For both React and Redux, I suggest literally copying React Router. First section: live code examples. Second section: "philosophical" concepts, side-by-side with code examples. Third-section: API. Again, side-by-side with code. Moar code.

[markerikson]

Had an extended discussion with someone on Reddit about the docs structure.

Quoting the main points here:

First off, let me just say that good documentation is hard, and clearly the Redux team has put a lot of effort in to it, which I give them many kudos for. I don't think there's any silver bullet to make the docs better, but I do think trying to reduce the signal to noise ratio and trying to teach Redux in context rather than on its own would help.

Subjectively it feels like everyone working on the project has forgotten what it's like to be or observe a new Redux learner. If they watched one I think they'd notice there's an overwhelming amount of info on the GitHub page, the Redux site itself, and the Web, and that the signal to noise ratio is a real problem (90% of that stuff is "noise" when you're just trying to grok Redux itself). On normal libraries this is fine, you muddle around through a page or two of docs filled with things you almost understand until you find what you need ... but Redux isn't a normal library, and reading about (say) selectors before you've fully grokked how mapStateToProps works can actually wind up confusing you more.

If Redux had what I consider to be "good" docs a new user could go to either the GitHub page or the Redux site, immediately see the obvious place to start, then start there with basically the content of https://redux.js.org/introduction/core-concepts, except with a much stronger emphasis on "here's our super simple non-Redux To Do (or whatever) app, and here's how you'd change it to manage state with Redux instead".

The current page shows only Redux code in a vacuum, which seems like a good idea except Redux is such a complex library (conceptually; in practice it's simple) that "random new code in a void" is exactly what's not helpful when you're trying to learn. The docs should (IMHO) lead a new user to say "oh, I understand the concept of an app with visible things, and normally in such an app I'd modify a "visible things" array directly ... but in this new paradigm the equivalent of that is sending a "change what's visible" action, and then having a case in my reducer which modifies the "visible things" array in state".

It's bridging that "paradigm gap" that I think makes Redux so hard, and I don't think you can make that leap easily by just looking at a reducer on its own. And while there almost certainly already is an article somewhere which explains Redux exactly like that, I certainly couldn't find it by going to the GitHub page or Redux site.

Also:

I can't make a PR to solve the signal to noise issue. Someone with control of the GitHub front page and site needs to make the decision to "direct" new users to the "correct" path of learning, and ensure that direction isn't overshadowed by the millions of other Redux details being presented, which really seems like something a maintainer needs to own.

P.S. Honestly the best thing I think you could do is observe new learners somehow. One of the hardest parts of documenting any library is just understanding what makes learning hard, and the better one understands Redux the father they move from being able to easily see the major issues learners face.

[UnderpantsGnome]

@markerikson as someone that has picked up Redux just in the last couple weeks, I can say for me a simple TodoMVC type app done as both plain React and done with Redux would have been tremendously helpful in wrapping my head around the Redux way.

[markerikson]

@UnderpantsGnome : For what it's worth, we do have a React+Redux implementation of TodoMVC in the examples folder of the repo, and you could probably compare that to the actual React implementation on the TodoMVC site.

But yes, I would love to see us add an "intermediate tutorial" that demonstrates building a slightly bigger app for real.

[markerikson]

I was talking to @tannerlinsley and @matthew-gerstman about this at lunch today.

I think what I'd like to see is a structure sorta like this:

• Quick Start
• What is Redux?
• Basic Tutorial
• Advanced Tutorial
• Building Real-World Apps
• Philosophy and Internals (?)
• Recipes
• FAQ
• API Reference

Right now, we're definitely missing a "Quick Start" section and a "Real-World Apps" section. I'd also like to rework the tutorial stuff so there's more of a focus on "do these things", and the "why" or "how did we end up with this approach" is in a separate section.

Most of the stuff from our current "Recipes" section should be under "Real-World Apps". A portion of "Configuring Your Store" would probably mostly go into the "Quick Start" section.

This could also tie in to both #2591 and reduxjs/react-redux#1001 .

Tim and I don't have time to tackle a rework like this, but I would gladly help provide guidance for anyone from the community who would like to help do this.

[markerikson]

One other thing to tie in here: I really want to push forward https://github.com/markerikson/redux-starter-kit , make it an official Redux-branded library, and recommend using it in our docs.

[markerikson]

We've thrown together a Dropbox Paper doc with a bunch of initial thoughts here: https://paper.dropbox.com/doc/Redux-docs-draft-rewrite-outline--AKdR4w1_Fho4CMyLjk5xUmI_AQ-692FKTM6G5SW0m3ggfzFE

[markerikson]

Huh, apparently I didn't say this yet.

I really want the docs to have runnable CodeSandbox examples everywhere.

[timdorr]

Can we implement it somewhere once just to work out the kinks?

[markerikson]

Sure, a proof-of-concept sounds good. Would be happy to have someone contribute a PR for that.

[dan-kez]

Ditto - happy to work on some CodeSandbox examples!

[markerikson]

Sweet. @dan-kez : as a tiny starter, could you just throw together any CodeSandbox example that uses Redux at all, look at the instructions for embedding runnable CodeSandbox examples in other pages, then try adding it to one of our Markdown docs files and submit a PR? My immediate question is simply what happens when an embed link is added to a Markdown file, and then run through the Gitbook build process - does it show up correctly in the final published docs, or does it get stripped out?

[dan-kez]

Definitely! I don't have much time tonight but I'll work on it running through that tomorrow.

[markerikson]

Random thought: should we maybe ditch the term "async actions"? It's never really been clear exactly what that term means.

[matthew-gerstman]

I usually go with thunks and action creators and mention that thunks can be async.

[markerikson]

Joel Hooks from Egghead left a comment in an HN discussion expressing interest in helping include resources somehow:

https://news.ycombinator.com/item?id=17791058

[markerikson]

Thoughts from Josh Comeau and Mark Dalgleish on teaching Redux: https://mobile.twitter.com/JoshWComeau/status/1024989819372556289

[markerikson]

Some good thoughts on the need for different types/sections of documentation (tutorials, how-tos, explanations, and references):

What nobody tells you about documentation

[markerikson]

Running a Twitter poll asking for what approach people think works best when teaching Redux:

https://twitter.com/acemarke/status/1048044685061750784

[sag1v]

@markerikson This is a great move.
I have one question, Do we want to separate Redux from React? (i think we should)
If so, i thinhk the "Quick Start" section should have 3 - 4 options.

Just an example:

Up and running with Redux

• Redux for React
• Redux for Angular
• Redux for jQuery
• ...

Each option should lead to a short and concise tutorial, no deep dive to reducers or data structure etc..
Just a small explanation about the job of a state manager and show me the code.

The tutorial should be a very small and basic application, I'm talking about basic as in a Counter App or something similar. single reducer, 1 action creator and no fancy stuff that will force us to explain things that relate to the current UI framework. something that any new developer can see and build within 15 - 20 minutes.

we can link key words like reducer, action creator etc to a relevant page that explains in more depth. but that's the reader's choice if he/she wants to go deeper at this point.

I also think we should have the next step section using the same application but adding more features to it (multiple counters? a reset button?)
Again this step should be completed within 15 - 20 minutes, more code less text.

After these 2 steps we can let the user re-read our steps but now with some more explanation on the what, why and how it works.

key take aways:

1. Do not bind Redux to React, let it be clear from the start it is a separate thing
2. More code less talk, short concise and easy tutorials (15 -20 minutes top) should be the first interaction for the readers.
3. Incremental complexity, i mentioned 2 steps but you can easily go to 3rd and 4th step with a Counter (or any other simple example) introducing side effects, reducer splitting etc.

[markerikson]

@sag1v : Yeah, I've already said that I'd like to expand / rewrite our coverage of how Redux interacts with a UI layer. See #2591 for my thoughts.

[sag1v]

Another thing that i just thought of, maybe we can have an official codesandbox account for Redux, each tutorial will have its starter kit as a repo there (you can link it to github as well).
This way we are giving the reader an option to start the tutorial immediately without setting the entire dev environment.
They can either use codesandbox or clone the repo from github.

[timdorr]

Closing in favor of #3592