[ameliaquining]

For what it's worth, I had the opposite experience learning React vs. Angular from the official tutorials. In React, there was a particular mental model that the tutorial aims to convey, and once I got it things started making sense pretty quickly. Angular had just so many details, the motivation for which isn't obvious at first, which made it just a little too much at once and I wound up bouncing off.

There is a particular problem with the React docs at the moment, which is that they still haven't decided what to do about hooks. These were introduced as an entirely new API that was competing with the old class-based one that React developers were familiar with (i.e., they do the same thing, but in a different way). So the way they handled that was by leaving the old documentation using the old class-based API intact, but also made a whole separate section entirely about hooks and how to do things with them. (I wound up largely reading the two in parallel and ignoring the details of the older class-based API; I found hooks easier to learn for the above reason, that there are fewer different complicatedly-interacting details to try to figure out all at once.)

I can't imagine that the long-term plan is to just keep things like this, since it's so obviously suboptimal, but perhaps it's difficult to decide what exactly to do.

[cehrlich]

It’s a difficult situation. A new React project should obviously use functional components and hooks. But there are still large code bases that use class based components, and I don’t see that changing too soon, so it needs to be taught.

Imo the docs/guide should include all the old stuff, but at the end and with a big warning saying “here’s the legacy stuff”.