React-redux: Rewrite React-Redux docs completely

[markerikson]

The current React-Redux docs aren't very helpful, for a lot of reasons:

• They're just a Markdown file in the repo, instead of being published in HTML form
• It feels very "dense" and jargon-heavy
• It doesn't clearly lay out the various options for connect and ways that you can use it
• It's primarily in API reference form, rather than a "how to"

We do also have the "Using React with Redux" page over in the main Redux docs, which is a bit more of a "getting started" page, but it's also not great.

So, I would really like to completely rewrite our React-Redux docs from scratch.

As a rough outline, what I'd like to see is:

• Quick Start (copy-pasteable examples that show how to add <Provider> and do a basic call to connect()
• How It Works (an explanation of how <Provider> makes the store accessible, and roughly what connect does internally to subscribe and extract data)
• Advanced Techniques / Recipes (examples of things like using the "factory function" syntax for per-component selector memoization)
• API Reference (something similar to what we have now)

I do already have a Gitbook setup configured for this, same as the main Redux docs. I should be able to get the react-redux.js.org domain name for this.

We can use some of the info from my Redux Fundamentals Workshop slides at https://blog.isquaredsoftware.com/2018/06/redux-fundamentals-workshop-slides/ to help fill this out.

There's a related Redux docs issue for revamping the Redux portion of the docs at https://github.com/reduxjs/redux/issues/2591 as well.

update

Let's track the outline and progress here:

• Introduction
  
  
  
  • [x] Quick Start
  
  
  • [x] Basic Tutorial
  
  
  • [x] Why Use React-Redux?
  
  
• Using React-Redux
  
  
  
  • [x] Connect: mapState
  
  
  • [x] Connect: mapDispatch
  
  
  • [ ] Using Selector Functions
  
  
  • [ ] Common Use Cases and Patterns
  
  
• Advanced Usage
  
  
  
  • [ ] Connect Options
  
  
  • [ ] Optimizing Performance
  
  
• How It Works
  
  
  
  • [ ] Conceptual Implementation (not entirely sure about this page)
  
  
  • [ ] Simplified Implementation Example (based on Dan's gist)
  
  
  • [ ] Actual Implementation Details
  
  
• FAQ
  
  
  
  • ???
  
  
• API Reference
  
  
  
  • [x] Provider
  
  
  • [x] Connect
  
  

[ConnorBryan]

Hey, Mark.

This request is right up my alley, let me do some research into this later on today and see what sort of timeline I'm looking at.

[markerikson]

Awesome, thanks - really appreciate it!

I'd previously discussed this with @jsonnull . One note from a discussion:

Since I was envisioning a breakdown into "High level concepts" ... "Recipes" ... "API Docs", I thought about making a PR which simply pulls apart the current docs into those categories.

Might be a place to start.

[timdorr]

Since Redux + React is such a common combo, I'd rather keep it all under the redux.js.org site. There's already a ton of React code in those docs anyways. And it also has the side effect of being more discoverable that way (one single search bar for both libraries).

We can point everything here to that page (or pages!). We can also consolidate the API reference, so there's one place for all the API docs.

[wgao19]

Hi, Mark!

Really happy that you talked to us about the rework on these docs. I'm back home & work now and I'd love to start helping!

For react-redux I have read the full api.md already and following your suggestion on this post I do have a few thoughts. It'd be my first time trying to contribute open source project, I do need some help and guidance on how I shall proceed --

1. Generate HTML docsite using gitbook, following the redux main doc

In the beginning of this post you mentioned:

They're just a Markdown file in the repo, instead of being published in HTML form

I think it's a good idea to follow the redux doc and use gitbook to generate the docsite. After this doc is re-written in better form, the main doc can either include directly or put a link to it. Both will work quite nicely if the react-redux doc is already in similar format.

2. "How-to" and "How It Works"

It's primarily in API reference form, rather than a "how to"

I do believe with a how-to guide with example it is much faster to get hands on on using redux with react. And this is perhaps a major chunk of work for this rewrite. Luckily I think the API doc is very well-written. I've personally learned a lot by reading it (thanks again for talking to me about this)! For this part, can I try to write a draft up? Any more resources or good examples of such guides I can learn from?

We do also have the "Using React with Redux" page over in the main Redux docs, which is a bit more of a "getting started" page, but it's also not great.

The "Using React with Redux" page looks like a simple guide with example. Should we work on that example directly?

How It Works (an explanation of how makes the store accessible, and roughly what connect does internally to subscribe and extract data)

I like the slides in your tutorial. Perhaps I can try writing up this section using them as a foundation?

3. Add Advanced Topic / Recipes / FAQ section

I think the _Recipes_ section of the redux documentation is very contentful. And the _FAQ_ section is absolutely amazing. I wish I can write such great docs myself. But for now I'm not very confident yet so here I think I need some more help or guidance here.

Oh and reading the current doc I'm afraid I also don't quite understand the factory function part so I need more resources to learn about it as well.

I see we have a troubleshooting.md file to work on (It actually contains some classic "traps" I ran into 😂).

4. Trim the current api.md to become the API Reference section

I think the current api.md is very well-written. After finishing writing the doc some of the content here may be trimmed. Leaving a neutral api documentation for reference.

So I'm thinking of a outline like this:

• Quick Start example + guide
• How It Works explanation based on this slides
• Recipes
  
  
  
  • ... (collecting topics)
  
  
• FAQ work on current troubleshooting.md
• API Reference trimmed of current api.md

I think in the beginning I was quite clueless about what can be done. And after reading the doc and the redux doc I think some of your conclusion above comes quite natural to me as well. Can I create a PR and start some of the pulling-aparts first and have you guys here help review and advice?

Thanks and looking forward to joining to help :)

[markerikson]

@wgao19 : Hiya! Thanks for looking into this. A couple quick thoughts:

• I did set up the initial Gitbook integration a while back. It's viewable at https://redux.gitbook.io/react-redux/ . I can see us going either way on whether it eventually becomes part of the main Redux docs page at https://redux.js.org , or whether it stays as a separate page (in which case I would want to get the https://react-redux.js.org domain name). In any case, we can focus on the content part for now, and worry about the publishing aspect later.
• I've got links to some really good "intro to React and Redux" tutorials in the Learning Resources#Using Redux with React page in the Redux docs. I would say we should try to use some of those as sources of inspiration for the "quick start" aspect. And yes, we can absolutely borrow from my slides for the "how it works" part.
• I talked about the "factory function" approach in my post Idiomatic Redux: Using Reselect Selectors for Encapsulation and Performance. In a new docs structure, we'd probably want to talk about the basics of using selectors in some kind of "Writing mapState Functions" or "Using mapState" recipes page, and then save the "factory function" aspect for an "Advanced Performance Optimizations" page.

@ConnorBryan , have you had a chance to look into any of this yet? Hopefully the two of you can collaborate on this.

[wgao19]

Thank you @markerikson that is a lot more learning resources to look into. I will read and watch them in the following few days and start drafting stuff.
@ConnorBryan It'd be great if we can collaborate on this! Though I'm not very experienced with open source contribution, perhaps I should pull up a PR that we can work on together?

[ConnorBryan]

@wgao19 I would be honored to work on this with you; are you on Discord at all? That's my primary place to communicate in real time; I think that might be the best way to hash this out.

[wgao19]

hey @ConnorBryan yes I am on discord @wgao19#0252

[ConnorBryan]

@wgao19 I'm having trouble locating you -- can you add connor#5456 ?

[markerikson]

Per discussion, we're setting up a Dropbox Paper doc to throw together an outline, same as we did for the main Redux docs:

https://paper.dropbox.com/doc/React-Redux-docs-draft-outline--AL9W1hkb6TLJ5se2~6G4awnSAQ-z5BoKAQVMVCo1SxGUhqbH

[maecapozzi]

I would also love to participate in the rewrite of the docs, if you'll have me. I have a bit of experience with redux, and a lot of experience with React. I also have written quite a few popular tutorials on React as well as webpack, so I might be helpful there. Is there still room for contributions @markerikson?

In the meantime, I'd love to start outlining @wgao19's "How it Works" section.

[markerikson]

@maecapozzi Hi, Mae! Yes, absolutely :) I think Carl Vitullo said you have some background with tech writing/editing too, which we could definitely use.

I just gave you edit rights to the Dropbox Paper doc, so go ahead!

(If anyone else out there is specifically interested in helping work on the outline / notes, comment here and open up the doc while logged into Dropbox, so I can give you edit rights.)

[markerikson]

@maecapozzi : sent a DM over on Discord/Reactiflux, if you can go check that. Thanks!

[Canopix]

Are you thinking about the translation in Spanish? May I help with the translation.

[timdorr]

Unfortunately, there isn't multi-lingual support built-in just yet: https://docs.gitbook.com/v2-changes/important-differences#multi-language-books

[Canopix]

Ohh, that's disappointing... Maybe with markdown we could make the docs on Spanish :(

[markerikson]

Okay, just merged in the new "Getting Started" page at #1017 . Looks great!

Erm. Except... I just fixed up the Gitbook integration, and it looks like the "Expand Code" stuff doesn't work right: https://redux.gitbook.io/react-redux/docs/gettingstarted . Guess we'll have to figure out another way to handle that. (I do plan on trying to get the react-redux.js.org domain name set up soon.)

[wgao19]

Thank you @markerikson !
The Gitbook generated page does look a bit off. It seems that the generated table of content on the right is broken by the code as well (._.) Since we also have the CodeSandbox links, perhaps we can remove the code wrapped with <details> for now?
Also I notice that the title is in CamelCase. How should we fix that?

[markerikson]

Yeah, let's delete the hidden code blocks for now. Other than that, don't worry too much about the Gitbook formatting - I'll need to figure out how to fiddle with the setup appropriately (probably by adding a gitbook.yaml file to point it to the right places).

Per discussion in chat, let's try to put together a practical "Using React-Redux" section next, like:

• Using React-Redux
  
  
  
  • Working with
  
  
  • Connect: Extracting data with mapState
  
  
  • Connect: dispatching actions via mapDispatch
  
  
  • Common Use Cases and Patterns
  
  

This would be a good place to at least start talking about selectors, including perhaps a separate sub-page on why and how to use selectors (at least at a basic level).

After that, I think we're looking at:

• Advanced Usage
  
  
  
  • perf optimizations, "factory" syntax, etc
  
  
  • the "hidden" options for connect
  
  
• How It Works
  
  
  
  • basic concepts (mostly explaining Dan's "connect-in-a-gist")
  
  
  • dig into the real internals -
  
  
• API Reference

[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]

For the "dispatching actions" page, Dan already has a good writeup on SO that we can base it on: https://stackoverflow.com/questions/34458261/how-to-get-simple-dispatch-from-this-props-using-connect-w-redux/34458710#34458710

[markerikson]

And, Dave Ceddia just posted an excellent You Might Not Need mapDispatchToProps post, inspired by my talk at ReactBoston. Great fodder for "dispatching actions".

[markerikson]

We now have the React-Redux docs being published at https://react-redux.js.org ! Built with Docusaurus, hosted on Netlify, and we've got deploy previews turned on for PRs. I'm very excited about this!

[sw-yx]

:) :) :) mark please ping me if i can help with anything on the netlify side. super glad and hope the deploy previews help with the rest of the ongoing docs rewrite

[markerikson]

Yep, loving it so far!

[zsid]

Hi everyone. How can I help with writing the docs? What will be best to start with?

[markerikson]

@zsid : Hi! You can see a list in the previous comments of some of the other pages we'd like to add.

Perhaps a good place to start would be to start adapting my post Idiomatic Redux: Using Reselect Selectors for Performance and Encapsulation into a docs page. If you'd like to work one of the other possible pages as well, that would also be great.

[zsid]

I will start with your suggestion @markerikson and work on selectors 😁Thanks.

[markerikson]

We should _totally_ add a "Why Should You Use React-Redux?" section to the docs, in the intro section. Base it on my workshop slides.

[wgao19]

Hi everyone,
I'm working on the "Why React-Redux" article now.
I have a working draft here, welcoming suggestions :)

[codedavinci]

Hello Y'all,

@markerikson & @timdorr quick suggestion for the intro, I noticed we have "Why use react-redux", I think it'd be really important to have a section describing "When to use react-redux " mentioning some of use cases that you could use for instanceReact.createContext to float state around the application, redux.getState() or simply raw state. Nowadays there are several ways of managing state in a raw fashion with react, but we still face some problems to flowy manipulate the methods (AKA Actions) that update this abundant state , and that's when react-redux - connect comes to play ! Something like this :

Introduction

• [ ] Quick Start
• [ ] Basic Tutorial
• [ ] Why Use React-Redux?
• [ ] When Use React-Redux?

I know the store is really important but I believe that the silver bullet of Redux is the dispatch, worth emphasize it, IMO.

what do you think ?

[markerikson]

Hmm. To some extent, it's not really a question of "When to Use React-Redux", but rather a question of "when should you use Redux in a React app, vs other options".

I'm somewhat less concerned about that topic as a whole, but I could see it being a reasonable thing to include. If you'd like to put something together, go ahead.

[codedavinci]

@markerikson, I am totally with you on that !
but It's also important to extend the knowledge that we can use Redux without the connect, with the api Redux.getState() + methods on demand through Redux.subscribe to update the store.
Actually, the majority of newcomers think that React-Redux is a requirement in order to utilize Redux which's not the case.

I think the place where I am trying to get is to demonstrate that the React-redux is optional in order to use Redux

Goal: draw a picture of a "life" without react-redux (Provider and connect ), using just redux.
And another picture using redux + react-redux, showcasing all the advantages of using (Provider and connect).

From an educational prospective, I believe that having a section that explain the topics above prior is the key to highlight the "Why use react-redux" section. It's extremely important for newcomers to see the difference, so they understand why they are choosing to adopt react-redux consciously, not just for tutorial /tooling habits.

I am gonna draft up a Why Use React-Redux page to follow the thread and I'll send a WIP-PR for you to take a look on the format.

Perhaps that can be implicitly mentioned at the top of the section of Why to use..

What do you think?

Thanks for the input !

[wgao19]

Hi all,

I have a draft for the connect() API docs here. Using paper for easier revisions.

This one is mainly a simple refactoring of the original api.md, with a few example added around certain sections.

Help / suggestions / edits are welcome :)

[markerikson]

Some updates today:

I bumped us up to Docusaurus 1.6.0, modified the config to remove /docs/ from the URLs, and changed the IDs for the mapState and mapDispatch pages to produce shorter URLs. I also added a Netlify redirects file to catch any existing incoming links to the old URLs. See #1096 .

After looking at the couple proposals for a "Why Use React-Redux?" page, I wound up writing a new one in #1097 and merged it. It's viewable at https://react-redux.js.org/introduction/why-use-react-redux .

Also left some comments on that connect API doc draft.

[wgao19]

I wish to add some docs around v5 -> v6 migration, or say v6 usage.

Some changes in v6 attracted a lot of questions from people haven't been keenly following up but need to use it. I have in mind the following topics, and I'm thinking to add those pieces to their related locations in the doc:

• providing custom context
• accessing store (or their app broken by accessing store via the legacy api)
• deprecation of storeKey and supporting multiple stores with custom context
• forwardRef
• list of peer libraries that need to upgrade

I have a working draft here, seeking for reviews / suggestions.

Addressing issues #1104, #1119, #1123, #1132.

[timdorr]

One thing I'd love to see in the docs: Testing! Patterns and guidelines to help folks out. I see a lot of confusion around this (especially with Hooks). We have a small section in the Redux core docs that should be migrated here: https://redux.js.org/recipes/writing-tests#connected-components

[armstrongl]

It doesn't look like this issue has had much activity recently, but I'm interested in helping out. I'm a technical writer and I'm currently learning React/Redux. If there's any documentation that's still missing or needs review (that can be understood by a beginner), I'd absolutely love to help out!

[timdorr]

@armstrongl Testing!

[markerikson]

@armstrongl , @timdorr : yep, docs on testing would be great. Also, any of the other unchecked items from the issue post should still be up for grabs. I'd be happy to help mentor you through working on any docs topics you'd like to contribute!

[markerikson]

Couple more things that we ought to cover in detail now that hooks are out:

• Hooks-specific details in the perf page we need to write
• Tradeoffs of using connect vs using hooks

Really, we probably ought to have a hooks page in the "Usage Guide" section. Not entirely sure what it should cover, but throwing that out there.

[armstrongl]

@markerikson I would love to collaborate with you on these! I'm rather new to programming and, needless to say React/Redux, but I'm picking it up quickly and I'll be able to use my noobness in the docs to 'lower the barrier to entry' so to speak

[markerikson]

@armstrongl : yeah, having an outside eye on things would be great (both from the "tech writer" perspective and a "new to this stuff" perspective).

Tell you what. Perhaps a good first task might be to do a review of the docs content we have right now. That would both help us fix any outstanding issues, and help make sure you're familiar with most of the concepts around React-Redux. That sound good?

[armstrongl]

@markerikson : sounds good! :)

I'll post an update here once I feel I'm ready.

[wgao19]

Hey @markerikson, I've been working on Flow recently and I have some notes on annotating connected components after upgrading Flow past 0.85. I think this version may have caused many confusions. Many people are unable to upgrade their codebases past 0.85 and / or may not know how to annotate connected components properly.

Would you like me to develop the notes into a doc for React Redux? And I'd like to hear your suggestions on the writing as well.

[markerikson]

Yeah, we really need a "Static Types" docs page in general. I've added that to the list.

@jessidhia , would you have any time / interest in helping fill out the TS half of a "Static Types" docs page?

[ThiefMaster]

Docs on how to test components using the useSelector hook would be nice. E.g. whether people should wrap in Provider with a mocked store, or mock useSelector, etc.

[markerikson]

Repeating myself, I _really_ want a "Static Types" docs page. It should definitely cover use with TS, and also Flow if possible.

I specifically want it to cover using the ConnectedProps<T> type described in these links:

https://github.com/DefinitelyTyped/DefinitelyTyped/pull/37300

https://gist.github.com/christianchown/05e084c78ec216070a5a2b80f0534d4b

https://dev.to/voronar/practical-typescript-react--redux-4enh

https://github.com/DefinitelyTyped/DefinitelyTyped/issues/31227

[JNaftali]

I'm kinda interested in taking a swing at this. What other things would you want to be covered?

My initial thoughts:

• Typing connect and components
  
  
  
  • using ConnectedProps
  
  
  • using type arguments (connect<StateProps, DispatchProps, OwnProps>)
  
  

Should selectors be part of it even though reselect is it's own package?
Should a section on typing the store be included even though react-redux doesn't really do anything special with the store aside from provide it?

[markerikson]

@JNaftali : great, thanks!

Yeah, I think the primary points would be around correctly typing connect and the hooks. I'd say some mentions of typing selectors would be appropriate, as that relates to both mapState and useSelector.

I don't think we need to cover the store here, unless there's some very specific aspects with code splitting that really relate to React-Redux specifically.

[JNaftali]

Sounds good. I'll see about getting a rough draft done ASAP so you (or anyone else) can give feedback

[JNaftali]

Oh, one more thing. You say you want the page to be "Static Types": does that include Flow? My background is all Typescript but I imagine their usage is similar enough that I could figure it out?

[markerikson]

Let's start with TypeScript for now, as that's more widely used.

I know @wgao19 uses Flow, and she'd previously worked on a Flow-related page that I don't think we ever merged in. She might be able to adapt some of that material for this page.

[wgao19]

Yah @markerikson I do have an open PR for this. Anything we shall add / edit to shape that up for what you have in mind about this section?

[markerikson]

Mmm... I'd have to go back and review what you'd written before.

I think my general observation was that the existing PR seems a bit too specific to "migrating past 0.85" or something, vs just "this is the right way to declare types for connect". Can you rework it along those lines, and maybe we pick it up from there?

[wgao19]

Yes sure, will submit a revision soon.

[renjithspace]

Hi guys, the documentation is very hard to learn for beginners. I just get started to read the doc and I facing difficulty to understand it. The Get started and Tutorial look the same as API reference. I think here needs a Step by step documentation approach like react did. And don't need to give complex logic in examples. I mean don't need to discuss the Todo app in examples. I think just a counter with increment and decrement is enough. Thanks

[markerikson]

@renjithspace : I'm not sure what problems you're trying to describe there. What do you mean by "Get started and tutorial look the same as the API reference"?

[renjithspace]

@markerikson I mean even on the introductory part of the documentation trying to explain about the concept of the API. It’s like written the documentation from API perspective, not from the users (developers) perspective. It’s just my feedback that I felt when I started to read the documentation. I think the same is happening to the beginners like me.
​
I watched a few tutorials available on youtube and I can see they explaining the basics in a simple way. That why I felt the same. Here is a reference: https://youtu.be/CVpUuw9XSjY

Here is a tweet regarding the same https://twitter.com/dan_abramov/status/1039570011986321408?s=20 if I didn’t misunderstand what he was meant.

Thanks

[rajanlagah]

Hey @markerikson
I have used react-redux in almost all of my react apps. I have good experience in REACT. And I would love to collaborate with you on these!
Will you please onboard me ?

[Gabri3l]

Hey @markerikson
I have used react-redux in almost all of my react apps. I have good experience in REACT. And I would love to collaborate with you on these!
Will you please onboard me ?

You can start by reading the Contributing guidelines. I would recommend trying to focus on an open issue and have specific questions.