Description
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.