The website could be revised for beginners - some points

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:

React makes it painless to create interactive UIs. Design simple views for each state in your application, and React will efficiently update and render just the right components when your data changes.

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

Build encapsulated components that manage their own state, then compose them to make complex UIs. Since component logic is written in JavaScript instead of templates, you can easily pass rich data through your app and keep state out of the DOM.

"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:

We will build a small game during this tutorial. You might be tempted to skip it because you’re not building games — but give it a chance. The techniques you’ll learn in the tutorial are fundamental to building any React apps, and mastering it will give you a deep understanding of React.

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.

先檢視 issue 中連結的 React 首頁與教學頁面，尤其是「Declarative」、「Component-Based」、「A Simple Component」和「Overview」章節。這個 issue 描述的是廣泛的結構與措辭問題，而不是特定的檔案或測試。完成這項工作需要將這些批評轉化為具體的文件修改，可能會透過聚焦的 pull request 來完成。