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

[Docs Rewrite] Meta-Issue: Overview #3592

Open
markerikson opened this issue Oct 29, 2019 · 15 comments
Open

[Docs Rewrite] Meta-Issue: Overview #3592

markerikson opened this issue Oct 29, 2019 · 15 comments
Labels
Milestone

Comments

@markerikson
Copy link
Contributor

@markerikson markerikson commented Oct 29, 2019

This is the parent tracking issue for all the work we'd like to do, and primarily serves to link to the other issues.

I'm initially basing this off my suggested outline for the new docs structure and content. This is absolutely not final, and I expect us to iterate on this a lot as we work through everything.

For now, I'm organizing the top-level task list by category / docs structure section.

Tasks

  • Guided Learning Paths (#3591)
  • General Content Improvements (#3593)
  • "Introduction" section (#3594)
  • "Tutorials" section (#3595)
  • "Recipes" section (#3596)
  • "FAQ" section (#3597)
  • "Real World Usage" section (#3598)
  • "Using Redux with a UI" section (#3599)
  • "Understanding Redux" section (#3600)
  • "Style Guide" section (#3601)
  • "Other" section and content (#3602)
  • Redux Starter Kit section (#3614 )

Planning / Discussion Topics

  • Docs writing guidelines and issue templates (#3609 )
  • Ideas from other docs sites and user feedback (#3615 )

Notes

Any pages that are moved around must update our Netlify redirects file so that visitors see the new page.

Questions for Discussion

  • Should we keep everything on a single docs-rewrite integration branch, or should we just go ahead and update master piecemeal as we go so that we get the initial benefits? I'm inclined to put changes into master as soon as we're happy with them.
@asedsami

This comment has been minimized.

Copy link

@asedsami asedsami commented Oct 30, 2019

I'm not sure if this is the right issue to say this, or if there are other people who read docs and tutorials on their phones while lying on the sofa, but please reduce the height of the purple part in mobile screens(horizontal).
The content takes only half the height of the screen which makes it hard to read the docs. note that "getting started", "API" and "FAQ" are already at the hamburger menu.
Screenshot_2019-10-31-01-14-20

@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Oct 30, 2019

@asedsami : can you file a separate issue for that? That would probably most relate to potentially updating Docusaurus to v2 (related: #3584 ).

@markerikson markerikson changed the title [Docs Rewrite] Meta-Issue: Main Tasks [Docs Rewrite] Meta-Issue: Overview Nov 6, 2019
@markerikson markerikson pinned this issue Nov 12, 2019
@markerikson markerikson mentioned this issue Nov 18, 2019
7 of 7 tasks complete
@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Nov 23, 2019

Not sure if it's better suited for this thread or #3593, but @dai-shi has put together a Remark plugin for Docusaurus v2 that lets you write snippets in TS, and automatically have a tabbed code block added with that snippet in both TS and plain JS:

https://twitter.com/dai_shi/status/1197816235058069504

We could maybe even take that further and have it do TS, ES6, and ES5.

@hbarcelos

This comment has been minimized.

Copy link

@hbarcelos hbarcelos commented Nov 26, 2019

Hi guys, I would be glad to help with this issue. I'll read through it tomorrow.

@hbarcelos

This comment has been minimized.

Copy link

@hbarcelos hbarcelos commented Nov 26, 2019

@markerikson do you think testing should be at the top level of the docs or be a subsection of one of the entries you suggested above?

Edit: I see that it would probably go under Recipes (#3596). I wonder if that's where the average developer would go first when looking for that.

@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Nov 27, 2019

It's under "Recipes" now. I'm inclined to move it under "Real World Usage" somewhere.

@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Dec 1, 2019

@hbarcelos: for reference:

@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Jan 1, 2020

Some feedback from a random HN user ( https://news.ycombinator.com/item?id=21927109 and https://news.ycombinator.com/item?id=21927800 ):

Biggest problem and reason why people (me included at the beginning) don't like Redux, you should know when you need it and you should use some abstraction layer (eg RTK). One cause could be the docs: while the maintainer try their best to educate a lot (also in this thread paired with interesting link building strategies), there is not quick and easy way to get into Redux. If you start with RTK's docs, you don't understand everything. Then, you need to read the Redux docs, then again back and forth. And this just takes too long to grok an actual simple API.

I meant the docs. It's like decades ago like when you wanted to learn Rails. Then somebody said stop! First learn Ruby... This is not how people learn. There's too much time between learning and trying, so there's no proper and face-paced feedback loop. Let's try to get into somebody's head who's ok in react and slowly wants to get into state management but having no clue of nothing:

His mind:

  • Ok, where should I start?

  • Which is the best? Mobx, redux, just ContextProvider or local state??

The poor guys falls into the rabbit hole and reads Reddit, HN, Github issues for hours, still not sure what to do; 2 hours later

  • Ok, let's try redux, for whatever reason, the maintainers seem to be quite active

The poor guy tries to decide if he should go just with redux/react-redux or rtk; former because it is good to understand the foundation, latter good because just to avoid boilerplate and that's what this acemark is promoting everywhere. The guy is still overwhelmed and don't forget doing decision is hard; it's one of the biggest struggles for humans

  • Ok, I guess I need to start with redux because it's the foundation.

He sees all the theory, new terms, the boilerplate and there's no fast-paced feedback loop; he just think heck and checks out mobx, 4 hours later

  • Man mobx is even more weird, totally unstructured and while mobx's maintainer seems to be a nice guy, my gut feeling is: stay away

  • Let's check out npmtrends, oh great, npmtrends shows that people also don't like mobx, cool, it has much less traction, decision made, nice

  • So, let's try redux again, maybe this time I start with RTK

We know what happens, RTK has better feedback loops but w/o the basic knowledge of redux he will struggle, 6 hours later after jumping back and forth the both docs

  • Lets stop here, tomorrow is another day.

He is out of flow, motivation is down, the next day he doesn't continue because the whole experience didn't feel good, he writes a post on HN that redux sucks steel and maybe looks the next week again on it

The situation is a bit like with kubernetes; until you have proper feedback loops with k8s you need days, with new k8s distros this got better but the biggest bummer are the k8s docs, too much, too verbose, so many new terms, no feedback loops at all and every k8s examples has minimum 100kb yamls.

What would be great and I know that writing good docs is much harder than actual code:

One and only piece which the reader should read first, which teaches him redux foundation, react-redux boilerplate and rtk within max 2 hours. After that he should have a working example AND should have understood it. No links to other resources, no nothing.

This main piece should be linked everywhere in the Github readmes of all redux relates projects in bold and h1 READ OUR MAIN PIECE FIRST, on all the doc pages and in all forum posts. I mean look at your post's footer in this thread: so many links, why? You need one entry point. RTK could be the entry point, it just needs a bit more flesh on redux and should be declared as the entry point of redux. There's one disadvantage though: with RTK as entry you'd kill the ecosystem around redux but IDK if you did this anyway by declaring RTK the standard way. And you would have a lot of redundant docs with redux/react-redux. Or maybe we need to merge all because maintaining redundant docs is just too much for an OSS project.

Whatever, all not easy but there must be a way because redux is the most underrated thing in the frontend world, it's def the best state management and RTK is a nice and long deserved abstraction.

Key point:

One and only piece which the reader should read first, which teaches him redux foundation, react-redux boilerplate and rtk within max 2 hours. After that he should have a working example AND should have understood it. No links to other resources, no nothing. This main piece should be linked everywhere in the Github readmes of all redux relates projects in bold and h1 READ OUR MAIN PIECE FIRST, on all the doc pages and in all forum posts.

I think this matches up with my desire for a "quick start" page that teaches RTK and React-Redux right away.

@hbarcelos

This comment has been minimized.

Copy link

@hbarcelos hbarcelos commented Jan 2, 2020

As someone who started learning Redux quite late comparing with the time I've known React, I tend to agree.

There's too many "intro to redux" tutorials out there. Not many of them are high quality. When you're starting, it's quite hard to separate the husk from the grain.

To me, the biggest issue is that common pattern of having different files for action types, action creators and reducers. This adds too much cognitive overhead. Ducks and RTK sort of fix this problem though.

It would be nice to have an authoritative piece built along side the community.

@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Jan 2, 2020

Unfortunately, there's nothing we can do about the mass of existing tutorials out there that are often of poor quality. All we can do is improve the docs, and even then, many times people do not even read the docs - they'd rather search for some tutorial on Medium or watch a course on Udemy.

@hbarcelos

This comment has been minimized.

Copy link

@hbarcelos hbarcelos commented Jan 2, 2020

Surely we can't force users to read the docs, but what we could possibly do is to help those who actually do that and have that self-contained intro you were talking about and furthermore having some quite thorough "Anti-Patterns" section with a compilation of those poor quality examples (no linking needed I guess) and the implications of using them in a real-world scenario for an extended period of time.

I guess the later is easier said than done, but we all have some unwritten rules we like to follow when working in complex apps. Maybe it's time trying to write them down.

@phryneas

This comment has been minimized.

Copy link

@phryneas phryneas commented Jan 2, 2020

Like the Redux Style Guide? ;)

Guess we'll gonna have that placed more prominently.

@hbarcelos

This comment has been minimized.

Copy link

@hbarcelos hbarcelos commented Jan 2, 2020

RSG does great on the "what I should do" part. If made easier to find, it would be good.

However, I think it falls short on the "what I should NOT do" question. I believe the main problem here is that most of the problems from anti-patterns in Redux are not so apparent immediately. It takes you a couple of weeks to realize you screwed up and now you have to make a relatively big refactor in your code base.

The hard part of writing a guide for that is that most of the problems are highly dependent on context. I think I started writing something about those cases when I made huge mistakes one or two times, but ended up giving up because actually explaining the problem would be too specific for the application I had at that time.

TBH, I haven't worked with Redux on enough complex applications to actually be able to extract those problematic issues from their context and state it as a general problem. Not sure if this can be done, but it would be quite nice to have.

@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Jan 5, 2020

Asked a series of questions on Twitter about why people avoid docs in the first place, and what sort of landing page / "getting started" info would be most useful:

https://twitter.com/acemarke/status/1213898963679633411

@markerikson

This comment has been minimized.

Copy link
Contributor Author

@markerikson markerikson commented Jan 26, 2020

Some feedback on the docs layout being hard to follow and making unstated assumptions:

https://twitter.com/jaflebol/status/1214562932660391939
https://twitter.com/jaflebol/status/1214563309254410244

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
5 participants
You can’t perform that action at this time.