Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Structuring reducers page #1930
One consistent nitpick I've noticed is that there are often 2 spaces after full stops, while the other docs use a single space.
Bah. So sue me for being old-school - I learned typing from a DOS program that taught that :)
But yeah, I figured there'd be formatting stuff I'd have to change. The code snippets probably need to change spacing from four spaces to two spaces as well, or something like that.
Hmm. Per-page, or for the section as a whole? Any suggestions?
I guess the exact format of the code snippets is a bit up in the air until our new lint rules (airbnb?) are decided on.
Line 74 of Basic Reducer Structure is an example to consider. IMO the line in bold is a key idea in the "Basic State Shape" section, but it comes 20+ lines into the section. To be fair, it is in bold, but it would be a shame if people missed an important idea because they are skipping sections that start off seeming familiar. I actually hadn't considered an "as a whole" summary, but that might be a good idea.
I've now read all the sections (and also gone back and read most of the
Here are some things I have been thinking about the overall structure. I am far from a technical writing expert, so feel free to tell me I am talking nonsense at any point!
I think there is a lot of cross over between "Basic Reducer Usage" stuff and the existing Reducer doc. I would be in favour of augmenting the existing Reducer doc where it is lacking and remove the "Basic Reducer Usage" material from the new docs.
There is also some cross-over between "combineReducers and Beyond" and "Reducer Composition"? Some re-organization might make sense there (or it might not make sense to treat them as distinct topics at all).
01: Basic Reducer Structure
There is a large overlap between this and the Reducer doc. I would be in favour
02: Splitting Reducer Logic
Remove "business function" and "case function" from the glossary (they aren't
03: Functional Decomposition
Drop the explanations of
Merge "Splitting Reducer Logic" and "Functional Decomposition" into a single "Reducer Composition" doc.
04: Using combineReducers
Remove the basic information about
05: Beyond combineReducers
Merge "Using combineReducers" with "Beyond combineReducers". Maybe "combineReducers and Beyond"?
06: Normalizing State Shape
07: Managing Normalized Data
I'm not sure about the Redux-ORM stuff here. It looks neat, but doesn't feel essential to me. Removing it reduces the doc size considerably.
Merge with "Normalizing State Shape"
08 - Reusing Reducer Logic
Merge with Splitting Reducer Logic and Functional Decomposition
09 - Immutable Update Patterns
This is very important stuff, Redux won't work as advertised if you get this
10 - Initializing State
I would be in favour of moving the pre-requisites to the relevant introductions, and drop this as a stand-alone document.
I also have a couple of wording suggestions and things, but I think this is
There is a lot here.
I know you've collected a lot of information about Redux best practices and have a good encyclopedia of information about it.
The challenge with that is that it's tempting to include it all here.
I can imagine similar sections talking about actions/action creators, async actions, selectors, etc., and I wonder how much would be too much for the core documentation. The longer it gets, the less likely people will read it.
The information here is really valuable, though, and having a distilled version of all of the information that's out there is a good idea.
Would it be worth splitting some of this into a separate online book about Redux in the real-world? Or is it OK to have this as part of the core documentation? I'm not sure I know the answer, but I think it's worth talking about.
A few other comments that didn't fit anywhere specific:
- It feels like most of the community has standardized on using the Flux Standard Action specification. Is it worth mentioning that and then re-working the examples to comply?
Wow. Well, I did ask for feedback :) Thanks, @randycoulman !
I'll go through and reply to a few of your comments now. Definitely sounds like I'm going to have to step back and rethink some of the overall approach, although I'm not exactly sure that that will involve.
Some very worthwhile discussion. I would say that reducers are more of a core topic than the others. While use of action creators / thunks / selectors is certainly "idiomatic Redux", it's entirely possible to write an app without those. On the other hand, every Redux app will have reducers.
Well, there certainly are a few of those out there already. However, I think there is a lot of value in having at least a good chunk of this in the docs. Having the stamp of "officialness" is kind of a big deal - see the reaction to Create-React-App as an example. It's also more easily visible than a random blog post somewhere.
It's certainly possible at least some of this could get moved elsewhere. As much as I like the Redux-ORM bit in "Managing Normalized Data", that might be a good candidate.
@markerikson Sorry if my review was too detailed or too overwhelming. I'm not suggesting that you need to re-work the whole thing, and I hope you didn't take it that way. You've got a lot of great stuff here, and I think it will help a lot of people.
And remember, I'm just one guy, so balance what I say against what others think.
Relevant suggestions: https://github.com/thejameskyle/documentation-handbook
@markerikson I know you wanted to make some changes, but I think this is pretty good as-is. And I think this is too important to leave hanging in a PR for too long! It can always be better, but we'll be accepting typo fixes until the end of time on all the docs
If you want to make any other final changes, feel free. Regardless, I'll merge this in on Sunday at some point. We can make future changes via subsequent PRs.
Seriously, amazing work on this stuff!
Heh. Thanks for the encouragement :)
The main thing I need to do atm is actually make sure it builds properly with the rest of the docs. I deliberately didn't worry about that yet, only focusing on the content. For example, I'm not sure about the numbered naming of the Markdown files versus the generated HTML filenames. I may need to rename the Markdown files to produce better HTML output.
Currently working on setting up a new gadget. I'll tackle this on Sunday, and let you know when I'm done. Please ping me before merging.
BTW, this is what you need to add to the docs/README.md to make it show up in the gitbook build:
* [Structuring Reducers](/docs/recipes/StructuringReducers.md) * [Basic Reducer Structure](/docs/recipes/reducers/01-BasicReducerStructure.md) * [Splitting Reducer Logic](/docs/recipes/reducers/02-SplittingReducerLogic.md) * [Refactoring Reducers Example](/docs/recipes/reducers/03-RefactoringReducersExample.md) * [Using `combineReducers`](/docs/recipes/reducers/04-UsingCombineReducers.md) * [Beyond `combineReducers`](/docs/recipes/reducers/05-BeyondCombineReducers.md) * [Normalizing State Shape](/docs/recipes/reducers/06-NormalizingStateShape.md) * [Updating Normalized Data](/docs/recipes/reducers/07-UpdatingNormalizedData.md) * [Reusing Reducer Logic](/docs/recipes/reducers/08-ReusingReducerLogic.md) * [Immutable Update Patterns](/docs/recipes/reducers/09-ImmutableUpdatePatterns.md) * [Initializing State](/docs/recipes/reducers/10-InitializingState.md)
I can put that at the top of the Recipes section. I think that looks best.
Right, that was going to be my next step once I got Gitbook building okay in my repo. Unfortunately, it looks like the current Gitbook setup symlinks from
Possible typo in "Using combineReducers":