Discussion: revamped docs content, structure, and teaching flow #3313
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:
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:
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
This should feel like a reference textbook. Lots of definitions, explanations of how to use the store etc.
Typescript, Vue, ReasonML, SSR, whatever else people are using redux with.
I think these should be things we mention in the getting started section and then link out to in the API reference section.
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.
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.
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":
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:
Just wanna clarify here.
When I said bare-bones I mean redux without react-redux, redux-starter-kit etc. I'm thinking manually calling
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).
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.
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.
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.
Thoughts on Current Sections
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:
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/ )
"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.
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.)
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:
Again, I wrote this, so I'm rather proud of it (and have heard lots of good comments about it). Main thoughts here:
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:
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).
This section has several objectives:
This is a direct
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):
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:
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
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.
(omitting the subsections)
And the "Usage" section, in particular, can have the following subsections:
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?
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.
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.
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.
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.
An inexperienced dev diving straight into advanced topics causes frustration on two sides:
Now, for my actual comments for the current docs, so I can establish a foundation to base my arguments regarding the revamped docs on:
That's it from me so far :)
I'd really like to get started on actually writing so I'm going to propose some process
@matthew-gerstman : sounds good to me. I am unfortunately going to have to focus on the React-Redux side of things for the near future ( per reduxjs/react-redux#1177 ), but happy to chip in on this side as much as possible.
I'd say we'll use my proposed outline as a starting point and tweak as necessary from there.
I've created a
We can probably start by shuffling around the existing pages that just need to be moved into new locations. This would require moving the files themselves, changing the structure in
referenced this issue
Apr 6, 2019
Some good feedback from a beginner who feels the current tutorial is too confusing:
referenced this issue
Jun 19, 2019
sounds like a great idea, honestly. People come back to Redux at all different levels and having four big buttons to cater to each person sounds very smart:
I do like the four sales pitch paragraphs you have, but I don't think the wording adequately explains what you get.
I'd change "centralized" to "organized". A big thing programmers tell me they dislike about Redux is how it smells like global state. This is not the case, Redux state is quite protected, so I think this needs to highlight how Redux isn't leaking your state everywhere. It's making it easily accessible and enables you to expose only the portions necessary for a particular piece of code, which makes that code way more testable as you don't have to mock massive structures to stand it up. I might suggest this:
I might also change "predictable" to something else. Most people who are considering Redux are using React, so they've already signed on to Flux. You might use this space instead to highlight Redux-Starter-Kit and how it allows you to set up Redux with less boilerplate than ever, the other biggest gripe people have with Redux. You might also play up your typescript support, which is a huge deal for a lot of code shops these days.
The "flexible" block is great, I'd just add another small call-to-action button there to go to the Ecosystem page. You might also make the top of that page more fun and prioritize things by use cases. Caching and persistence, analytics, form wizards, load-from-storage PWA support are probably the biggest topics here.
Hopefully these are useful thoughts!