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 reduxjs/redux#2591 as well.

update

Let's track the outline and progress here:

• Introduction
  • Quick Start
  • Basic Tutorial
  • Why Use React-Redux?
• Using React-Redux
  • Connect: mapState
  • 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
  • Provider
  • 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!

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

DefinitelyTyped/DefinitelyTyped#37300

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

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

DefinitelyTyped/DefinitelyTyped#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.