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 <Provider> 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 <Provider>
  • 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!

[swyxio]

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