Closed markerikson closed 4 years ago
markerikson
commented
7 years ago 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
commented
6 years ago 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
commented
6 years ago 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
commented
6 years ago @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
commented
6 years ago @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
commented
6 years ago 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:
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 https://github.com/reduxjs/react-redux/issues/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
commented
6 years ago 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
commented
6 years ago 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
commented
6 years ago Huh, apparently I didn't say this yet.
I really want the docs to have runnable CodeSandbox examples everywhere.
timdorr
commented
6 years ago Can we implement it somewhere once just to work out the kinks?
markerikson
commented
6 years ago Sure, a proof-of-concept sounds good. Would be happy to have someone contribute a PR for that.
dan-kez
commented
6 years ago Ditto - happy to work on some CodeSandbox examples!
markerikson
commented
6 years ago 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
commented
6 years ago Definitely! I don't have much time tonight but I'll work on it running through that tomorrow.
markerikson
commented
6 years ago Random thought: should we maybe ditch the term "async actions"? It's never really been clear exactly what that term means.
matthew-gerstman
commented
6 years ago I usually go with thunks and action creators and mention that thunks can be async.
markerikson
commented
6 years ago Joel Hooks from Egghead left a comment in an HN discussion expressing interest in helping include resources somehow:
markerikson
commented
6 years ago Thoughts from Josh Comeau and Mark Dalgleish on teaching Redux: https://mobile.twitter.com/JoshWComeau/status/1024989819372556289
markerikson
commented
6 years ago Some good thoughts on the need for different types/sections of documentation (tutorials, how-tos, explanations, and references):
markerikson
commented
5 years ago Running a Twitter poll asking for what approach people think works best when teaching Redux:
sag1v
commented
5 years ago @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:
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.
Redux to React, let it be clear from the start it is a separate thingCounter (or any other simple example) introducing side effects, reducer splitting etc. markerikson
commented
5 years ago @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
commented
5 years ago 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.
markerikson
commented
5 years ago Some discussion about how to present immutability, Immer, and redux-starter-kit in the docs: https://mobile.twitter.com/sovietfish/status/1046097832820842501
ghost
commented
5 years ago Just wanted to add my perspective as some one who has used redux before, but spent a lot of time yesterday rereading the docs to try and get a better understanding. I mostly agree with what's been said, however, for me the part going through middleware step by step was by far the most useful. It took a couple of reads, but once it clicked, I felt like I understood redux on the whole much better. Going through the real-world example and trying to implement some of the patterns was also very helpful for me. I thought the rest of the documentation was quite good as well and very thorough. However, this is from the perspective of someone trying to get a deeper understanding and who has used it before.
From the viewpoint of someone whose never used redux and is looking for the 10 minute tutorial the docs are rather poor because they don't function well as that 10 minute tutorial that's going to get you up and running. The information is all there but as someone else said, the single to noise ratio will probably have beginners googling "how to use redux" rather than wading through "Motivation", "Core Concepts", "Three Principles", and "Prior Art."
I think the easiest solution would be to have a big link at the top of the home page that says 'Intro to redux quick start' that provides that basic tutorial. The second link to 'The basic tutorial in the Redux docs' provides that somewhat, but it's not featured that prominently and it's a link to another page with five links for the basic todo app. I think the todo app is good, but could be overload for some people. Then there's the gist section midway down the page which gives you the bare minimum code but its probably insufficient by itself.
Imo the docs are like an A- as reference or for someone trying to understand redux and whose prepared to sit down and read everything start to finish, but like a D for an impatient beginner. Which is why I think having a prominent link to some sort of quickstart guide would be the best way to get beginners on the right path so that you can boost the signal without muffling the (quite useful) noise.
geeofree
commented
5 years ago Hi there :wave: moving my thoughts from the discord chat to here about what I feel the docs should change for the Introduction section:
Should be short and sweet — right now it feels like it explains why redux was implemented in a very concise way instead of why it should be used (in simple terms).
Something like
Redux is the solution intended to manage JavaScript application data while also having a way to describe which and how these data changes overtime, etc..
Should be where Basics section is IMO and again should be able to explain in as short and sweet as possible about how people are to use redux.
Probably add sections to each core concept and what their intended purpose is, e.g:
STATE — plain javascript object that contains whatever data your app needs, should be immutable, then state example. ACTIONS — plain javascript object thats describes how a state is to be modified, then action example. REDUCERS — a function that accepts the old and incoming state (described from actions), then reducers example.
Then give a very brief and simple example of how these things intertwine and what happens with what
I think this should be removed? Or at least maybe move parts of this into the other earlier intro sections. IDK to be honest, but this section feels confusing to me — the part about the Single source of truth having to do with server side stuff or hydration feels like something people shouldn't be concerned about in the intro.. Read-only state I think should be stated earlier (like in the core concepts). Pure functions should be move to the Motivation or maybe even explained into Core Concepts section
Should be move out of the introduction and into their separate section IMO
dceddia
commented
5 years ago I think most readers of the docs fall into 2 buckets:
connect or whatever.The beginner's background varies. Maybe they're a developer of 30 years trying to "modernize" and learn the new tech. Maybe they're just a few years into their developer career. Or maybe they're fresh out of a bootcamp, or haven't even learned JavaScript yet. In common, they share the fact that they don't understand Redux yet.
Related to Redux, their experience will vary too: some have read tutorials or watched videos for days and it hasn't "clicked" yet. Some are at the very beginning of that journey -- maybe they know some React, and now it's time to learn Redux. Or maybe they know zero React, but believe React+Redux should be learned as a pair.
Or maybe they're not using React at all? I'm pretty sure that is a small group though. I may be wrong, but I think most people are using Redux with React, and to give that group a good experience, it'd be good to write the docs with that assumption in mind. Still worth mentioning that Redux is a standalone library, and that it can be used with more than React... but while making the React path clear.
Some folks are learning because they've been handed an existing project that uses Redux. Some want to find a job. Some just want to learn the latest stuff to stay relevant.
So there are a lot of dimensions, and a lot of variation, and how can one set of docs serve all those different angles? And is it even the job of "docs" to serve as a tutorial? I dunno. Good question.
If the docs are a learning resource though, maybe it would be good to let people self-select: "I'm learning" or "I need to look something up".
For the "learning" group, IMO it's easiest for them if the information is presented linearly. Right now there is a lot of good content covering a lot of useful topics, but it's hard to nagivate. Where should I click first? "Introduction" looks useful. Then, maybe "Learning Resources"? There's a LOT of stuff there. Ok, maybe "Basics" then. That page tells me it's incredibly simple, and "Actions" is the first one so I guess I'll start there -- and that page is written as if it's the first step, so that's comforting.
If we make the assumption that they're probably using Redux with React, then I think a linearlized flow goes something like this, in the context of a Todo List example:
connect up the React components, talk about mapStateToProps and dispatchThere are more details to be filled in there -- like it might be good to explain Array.reduce before explaining reducers, or at least mention the parallels... and explaining how the reducer needs to return new state, and why immutability matters... and I sorta glossed over the part where the React components get written (is it better to start from scratch, or to start with a stateful React app and replace state with Redux? 🤷♂️ )
Anyway, just some food for thought :)
joshwcomeau
commented
5 years ago Following up from a Twitter thread, I think there are multiple audiences to consider with the docs. I think the docs do a great job for intermediate/advanced users, or for people who just want an API reference to understand the signatures for different methods.
When it comes to the beginner - someone still becoming comfortable with React or another JS framework, and looking to add a solution for global state management - I wonder if another approach might work better.
"The basics", for example, includes a lot of information, and I'm not sure that most of it is relevant for this type of person:
I think framing it this way (as "Just the basics") implies that readers should understand each of the resources provided - which is made trickier by the fact that some resources listed are themselves lists of other resources - just to have a basic/superficial understanding of the tool.
I've taught Redux to several people, most notably to multiple cohorts of interns at my workplace. This has been challenging since in most cases, the interns have never used React, and many are new to Javascript. I've learned quite a bit from these experiences.
My first attempt was to do something similar to the basics section: go through the terms 1 by 1. Explain what actions are, what reducers are, etc. I made care to really try and make each term concrete and clear - I must have said "an action is just a plain javascript object that describes the change that's happening" 3-4 times. At the end of the session, several people said they still didn't know what actions/reducers were, that it was too much jargon too quickly. One piece of feedback was "he didn't even explain what actions were", which sticks with me because I definitely did, multiple times, but ultimately I wasn't able to make that abstract concept clear, no matter how many times I repeated myself.
My most recent (and most successful) attempt started by explaining 2 things:
I then built a mini-redux, in realtime, using the Chrome console. When the reader knows how reduce works, it makes understanding actions and reducers so much simpler. And understanding how stores work (and bindings like react-redux) is much easier when event emitters are taught first.
I don't know what role the Redux docs should play in covering JS fundamentals, but I think this info is critical for folks looking to understand Redux. At Khan Academy (where I work), we focus a lot of "swiss-cheese gaps", the holes we have in our knowledge that make it hard to advance in a subject. I wonder how much of the "redux is hard" sentiment is because people try to make sense of actions and reducers before they have a solid grasp of the fundamental concepts.
markerikson
commented
5 years ago Other docs sites that look really nice (style, structure, content, landing page):
https://facebook.github.io/create-react-app/ https://fbflipper.com/ https://jestjs.io/ https://babeljs.io/ https://bemuse.ninja/project/ https://captainduckduck.com/ https://fuse-box.org/ https://gulpjs.com/ https://hemerajs.github.io/hemera/ https://docs.nteract.io/#/ https://openpowerquality.org/ https://pnpm.js.org/ https://prettier.io/ https://react-native-training.github.io/react-native-elements/ http://react-slate.surge.sh/ https://resthapi.com/ https://docs.stackery.io/ https://textlint.github.io/ https://vasern.com/
https://reactjs.org/ https://vuejs.org/ https://www.emberjs.com/ https://angular.io/ https://lodash.com/ https://laravel.com/ https://symfony.com/
alexkrolick
commented
5 years ago Redux Bundler's docs have a great structure:
Prettier's docs are similar, plus a runnable example in the "Playground"
markerikson
commented
5 years ago For what it's worth, the top 10 pages over the last week have been:
So, clearly a lot of people wanting to learn.
matthew-gerstman
commented
5 years ago I think @alexkrolick 's outline is pretty on point. The most important flow IMO is the new user flow. We should optimize for them and then let advanced users find the reference docs below.
markerikson
commented
5 years ago Agreed. I'm going to open up a new issue soon to specifically discuss what the intro / tutorial content flow should look like.
timdorr
commented
4 years ago Closing in favor of #3592
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:
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.