Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite React-Redux docs completely #1001

Open
7 of 14 tasks
markerikson opened this issue Aug 17, 2018 · 61 comments
Open
7 of 14 tasks

Rewrite React-Redux docs completely #1001

markerikson opened this issue Aug 17, 2018 · 61 comments
Labels

Comments

@markerikson
Copy link
Contributor

markerikson commented Aug 17, 2018

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
Copy link

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
Copy link
Contributor Author

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
Copy link
Member

timdorr commented Aug 17, 2018

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
Copy link
Contributor

wgao19 commented Aug 29, 2018

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
Copy link
Contributor Author

@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
Copy link
Contributor

wgao19 commented Aug 30, 2018

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
Copy link

@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
Copy link
Contributor

wgao19 commented Sep 2, 2018

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

@ConnorBryan
Copy link

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

@markerikson
Copy link
Contributor Author

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
Copy link
Contributor

maecapozzi commented Sep 6, 2018

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
Copy link
Contributor Author

@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
Copy link
Contributor Author

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

@Canopix
Copy link

Canopix commented Sep 7, 2018

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

@timdorr
Copy link
Member

timdorr commented Sep 7, 2018

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

@Canopix
Copy link

Canopix commented Sep 7, 2018

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

@markerikson
Copy link
Contributor Author

markerikson commented Sep 17, 2018

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
Copy link
Contributor

wgao19 commented Sep 18, 2018

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
Copy link
Contributor Author

markerikson commented Sep 18, 2018

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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
Copy link

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
Copy link
Contributor Author

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
Copy link
Contributor

JNaftali commented Oct 29, 2019

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
Copy link
Contributor Author

@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
Copy link
Contributor

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

@JNaftali
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor

wgao19 commented Oct 29, 2019

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
Copy link
Contributor Author

markerikson commented Oct 29, 2019

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
Copy link
Contributor

wgao19 commented Oct 30, 2019

Yes sure, will submit a revision soon.

@renjithspace
Copy link

renjithspace commented Aug 11, 2020

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
Copy link
Contributor Author

@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
Copy link

renjithspace commented Aug 11, 2020

@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
Copy link

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
Copy link

Gabri3l commented Jan 4, 2021

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.

@markerikson markerikson unpinned this issue Jun 25, 2021
albertodev7 pushed a commit to albertodev7/react-redux that referenced this issue Dec 8, 2022
## What does this PR do?
Regarding reduxjs#1001, a few follow up fixes on the `mapState` piece.

## Summary of the changes
- Site header:
  - Remove "Troubleshooting"
  - Uppercase "API"
  - Add "Using React-Redux" and let it direct to the `mapState` doc
- Site sidebar:
  - Uppercase "API"
  - Add a dash to "React-Redux"
- Site footer:
  - Add "Using React-Redux"
  - Align all link labels with section names on the sidebar
- Doc changes
  - `<ConnectedTodo>` typo
  - Changed a wording at the table for consistency
  - Add "./using-react-redux" directory and move in mapState.md
  - Add `array.slice` to the list of options that create new references
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests