gaearon
commented
5 years ago Open to seeing your specific suggestions in form of PRs. I agree on the overall points but don’t forget the documentation has to cater to all audiences. I’d say that it’s currently slanted towards people with existing programming experience but new to React or web. Whichever way we change it, we should avoid losing that audience.
We plan to revamp the docs at some point so it’s good to collect this kind of feedback. But also, if you have simple fixes like removing fluff, feel free to go ahead and send them.
brunolm
This is probably not the best time to be making this issue given all the translations are underway, but when I look at the home page and tutorial page, there are things that probably steer beginners away immediately.
One of the things I try to do is write content that both beginners and experienced developers can digest easily. This means creating a "story" that introduces hard concepts slowly, and starts off with how the library can help the user. Why should they want to use it? This means minimizing the use of jargony terminology until later on, but not to an extreme extent that it seems patronizing to experienced developers.
I'm writing this from my perspective circa 2016 to early 2017, when I was still a beginner. I'd like to think I've come a long way since then, but some of this is still pretty fresh in my mind. When I say "beginner", I mean someone who probably isn't experienced with another programming language, and only dabbled with some jQuery before. Many concepts that React introduces are completely alien to them. That was my experience at least.
React is also extremely popular, and its popularity is only accelerating. Maybe you could argue this proves the current documentation is already fine as it is. I think many beginners may be looking at alternative sources such as video tutorials on YouTube. For experienced developers the website is pretty amazing as is.
Home Page
https://reactjs.org/
Top header
The header is fine as it is. In fact I think the slogan is perfect.
Declarative
I think this one is problematic. "Declarative" as a term is something most beginners have never heard before. Also consider the subtext:
The words "simple" and "simply" should probably be avoided at all costs, unless talking about very basic HTML & CSS. To a beginner, none of this is "simple" because it goes completely against what they know about the core basics of web development. What does "render" mean, or "efficiently update"? It honestly has no meaning to a beginner just yet.
Also, the word "painless". Unfortunately most beginners are going to experience a lot of pain when using React for the first time. It's not painless at the beginning. I think there should be emphasis on this somewhere. For example, I loved the "Give it 5 Minutes" heading back in 2013 (viewing from Wayback Machine).
Component-Based
"Encapsulated" is a scary word for beginners. Most also don't know what "state" is, unless they're already quite experienced.
Learn Once, Write Anywhere
This one appears to be fine.
Moving to the next section. This is the main part that's going to steer beginners away. You're showing React in its full glory, which to newbies, is incredibly intimidating. I think this should be avoided.
A Simple Component
This isn't "simple" to most beginners. It looks scary, trust me I remember 🙂 The subtext is also full of too much jargon that they don't care about yet.
Allowing them to edit the code doesn't make it any more friendly. There's only a couple places a beginner could change the code to experiment without it breaking. As soon as they accidentally break something, it's going to turn them off. And I think that's really easy to do.
The next headings are more of the same, but even more extreme.
Tutorial
https://reactjs.org/tutorial/tutorial.html
Just want to say I love the intro here, it feels quite welcoming:
However, the next part drags on for too long. It's full of too much disclaimery stuff without getting to the core content quickly enough.
Overview
I think this is where it begins to fall apart. Once again, difficult concepts are being introduced too soon. I am willing to bet many people close the tab at this point.
There is more to say about the tutorial page and other pages on the website, but at that point it would be more helpful to start creating PRs.
I hope I made my points clear. I don't want to be overly critical of the React documentation because for experienced developers it's amazing. I just think the writers were suffering from the Curse of Knowledge, or maybe didn't anticipate React penetrating into the beginnersphere as much as it did. It's effectively becoming the new jQuery.
I have some ideas for how it could be improved and might draft a WIP to showcase. Instead of simply rewording the documentation, I think there needs to be structural changes as a whole.