Create the Redux Essentials page, take 2

[markerikson]

PR Type

Does this PR add a new page, or update an existing page?

Adds the new "Quick Start" "Redux Essentials" page

Update: Ready!

Jump ahead to the request for review feedback:
#3740 (comment)

Checklist

• Is there an existing issue for this PR?
  • [Docs Rewrite] Create "Quick Start" page #3674
• Have the files been linted and formatted?

What docs page is being added or updated?

• Section: Tutorials
• Page: Quick Start

For Adding New Content

What kind of content category is this page (tutorial, how-to, explanation, reference)?

The "Quick Start" page is a form of tutorial, but intended to demonstrate the "fastest" / "easiest" / "correct" way to use Redux without explaining why things work this way.

Who is the intended target audience?

Beginners who know nothing about Redux, yet.

What knowledge are we assuming they have?

• JS syntax: ES6, async/await, object spreads
• React: components, hooks
• Other: HTTP / AJAX, fetch

What are the intended results or takeaways from reading this page?

Readers should be able to mimic the demonstrated patterns to create a basic React+Redux app that does some CRUD work.

What is the most critical info they should learn?

• Redux is a tool for managing state outside of your React components
• The Redux Toolkit package is the simplest and recommended way to use Redux
• Key React+Redux APIs (configureStore, createSlice, useSelector / useDispatch)
• Immutability is vital, but either requires hand-written updates or use of RTK+Immer "magic"

Status

This is a second attempt at writing this new "Quick Start" page, and supersedes #3675 .

Currently an early WIP, but I want the PR preview up so I can start getting feedback as I go.

I've gone ahead and created a new "Tutorials" category, moved the two existing "Basic/Advanced" tutorials under there, and added "Quick Start" under "Tutorials". This doesn't change any of the existing URLs, it's just sidebar organization.

Page Link

Direct link to the actual page being worked on:

https://deploy-preview-3740--redux-docs.netlify.com/tutorials/quick-start/quick-start-part-1

[netlify]

Deploy preview for redux-docs ready!

Built with commit 16fcb8f

https://deploy-preview-3740--redux-docs.netlify.app

[github-actions]

Size Change: 0 B

Total Size: 8.97 kB

ℹ️ View Unchanged

Filename	Size	Change
dist/redux.js	6.41 kB	0 B
dist/redux.min.js	2.56 kB	0 B

_{compressed-size-action}

[msutkowski]

I read this over a few times and overall it reads extremely well.

[markerikson]

At the moment this is looking like it's going to be two parts:

• Part 1: just explanation of terms and concepts, and walking through the actual structure of a React+Redux app using the standard CRA "counter" template.
• Part 2: hands-on building a small blogging app using RTK.

I've got the first draft content of Part 1 basically done, and will try to put together Part 2 over the next few days.

I'm not convinced this sequencing and explanation is the right approach, but I want to get a complete first draft written so that we have something concrete to get feedback on so we can iterate from there.

[markerikson]

Just pushed a sizeable update:

• Addressed most of the comments from @taniarascia and @Matvien
  • Removed some unnecessary explanations and a leftover example
  • Clarified several explanations
  • Added a section on "Immutability" under "Concepts", before we even get to "Reducers"
• Split Part 1 by extracting the entire "counter app walkthrough" section into a new Part 2, and renamed the later pages accordingly
• Fixed up several TODO comments
• Added a Redux dataflow diagram. (I'd like to redo this with some tweaks, but I need to figure out how to create good animated diagrams first)

Still debating renaming this. The best alternate ideas I've had so far are "Essentials Guide" and "Practical Guide".

[las3r]

Part 2:

Detailed Explanation: Thunks and Async Logic
But, in a real Redux app, we're not allowed to import the store into other files, especially in our React components.
It is allowed and it works, but it is bad practice. Why is this a bad practise? Make us better devs by telling us why ;-)

[markerikson]

Ready to Go!

Haven't gotten as much meaningful feedback as I'd hoped, but I think this is basically ready to go.

I've renamed it from "Quick Start" to "Redux Essentials". It's 25K words and 6 pages, so it's not "quick" at all, but it is the key information you need to get started using Redux.

I added a link to this as "Tutorial" in the header/footer, emphasized it in the "Getting Started" page, and added a new "Tutorial Index" page that describes the differences between the two sets of tutorials.

I also cleaned up the "Getting Started" page to remove most of the external article links, since there were too many of them and people have said they were overwhelming.

I plan on merging this in tomorrow :)

[markerikson]

Going LIIIIIIVE!