[Docs Rewrite] Discussion: Ideas from Other Docs and Resources

[markerikson]

There's a lot of great docs sites and teaching content out there, both for Redux and for things completely unrelated. I'd like to see what specific things we can learn from these other sites and how we can apply those to improve the Redux docs.

Suggested Sites for Comparison

This is not an exclusive list - if there's other good sites or tutorials we should learn from, please comment with the site and what ideas we should take inspiration from.

Docs Sites

• React: https://reactjs.org
• Vue: https://vuejs.org/
• Angular: https://angular.io/docs
• Ember: https://guides.emberjs.com/release/ , https://api.emberjs.com/ember/release
• NgRx: https://ngrx.io/docs
• Django: https://docs.djangoproject.com/en/2.2/

Tutorials

• Dave Ceddia: A Complete React-Redux Tutorial for Beginners
• Valentino Gagliardi: Complete React-Redux Tutorial for Beginners - The Definitive Guide
• Mark Erikson: Redux Fundamentals Workshop slides

User Survey

I put up a survey over a year ago asking for feedback on improving the docs.

The survey results are browsable here.

Dan's Thoughts

Dan specifically commented a while back on Twitter (https://twitter.com/dan_abramov/status/1039570011986321408):

My biggest regret with Redux is explaining it in terms of API instead of how to “think in it”. I underestimated the temptation to twist it into a familiar conceptual model — and that it’s flexible enough to allow these contortions.
When 10 people say “I dislike Redux” they might mean 10 completely different things. And they often have nothing to do with Redux itself, but with how the code they worked with is structured, or with the examples they learned from.
If you copy paste some action creators and reducers handling FETCH actions over and over and over again, you’re probably using Redux in a different way than I imagined people would do. I’m sorry for all the repetitive code you felt you needed to write. That’s my fault.
Same goes for having 20 actions with types like SET_A, SET_B, SET_C, and dispatching them from a long-ass async action creator. Also not how I imagined people would do it. Again, sorry I didn’t explain this clearly.

[markerikson]

A few initial takeaways:

• Vue docs:
  • "Style Guide" page provides opinions and guidance on best practices
  • Totally separate sections for "Guide", "API", and "Cookbook", with different kinds of content and different assumptions on user background
  • Scrimba links for lessons in the tutorials
• NgRx docs:
  • Immediate info on "why" and "when" to use NgRx
  • "Getting Started" highlights key concepts and shows a data flow diagram immediately
  • "Installation" is a separate page
  • "Actions" has good principles on modeling actions ("events", etc)
  • Introduces selectors right away as a top-level concept
• Dave Ceddia's "Complete Tutorial"
  • Great diagrams
  • Starts from React code, refactors to Redux
  • Introduces concepts while walking through tutorial code
• Some partial notes on the survey:
  • What content should the front page have?
    • "Getting Started" link, API docs link, short description, installation instructions, reasons to use it and explanation why, runnable code example
  • How to deal with "prerequisite concepts" like immutability?
    • Add a "prerequisites" docs section with info (44%)
    • "Prerequisites" with just links (25%)
    • Explain inline in tutorials (19%)
  • Add "Guided Learning Paths" to the docs?
    • Very Important (65%), Maybe Important (30%)
  • How valuable are diagrams and runnable examples?
    • Very Important (75%), Maybe Important (23%)
  • What topics need diagrams?
    • Data flow
    • Architecture

[markerikson]

While I was working on the "Redux Essentials" tutorial, I took the time to go through about 25 different tutorials of various kinds: Redux blog post tutorials, non-Redux tutorials, other JS web frameworks, and some back-end web frameworks as well.

After writing down a lot of notes on each tutorial, I collected a summary of what I liked and didn't like here:

https://www.notion.so/23c1be94861e41dc82ecb0c2b18aa138?v=d7704772636f4972a4bb066a8ca92bba

[itz-Me-Pj]

hi @markerikson @EskiMojo14 as I am seeing there are a lot of outdated docs and examples in this repo. Pls suggest me or guide me where I can find the latest resources to update the docs and examples of the repo. And also is the notion provided with resources is still valid?

[markerikson]

@itz-Me-Pj I'm not sure I understand what exactly you're asking - what do you mean by "latest resources to update the docs" ?

Note that this specific issue was written when I was attempting to write the "Redux Essentials" tutorial, and so the ideas that I was collecting were specifically focused on things I wanted to do while writing that tutorial.