High-level reorganization

Per some discussions on Reactiflux (w/@markerikson), thought it might be a good idea to start tracking some high-level ideas for organizing the docs.

What's great about the current docs

• Lots of examples
• Concepts grouped by domain (forms, styling, etc.)
• Runnable code
• Real-world app tutorial
• Good search feature through Algolia

What's not so good

• Too many paths through the docs: On the 1st page you can either scroll down and go through the examples, Get Started and jump to Hello World (bypassing Install), or go the Tutorial
• Not entirely clear what the distinction is between "Getting Started" and "Tutorial"
• API docs feel hidden

Other projects with great docs

... and what can be learned from them...

• Vue has been cited lately as having great docs that "can get you off the ground in 20 mins" (paraphrasing). In particular it's easy to read the docs top-to-bottom.
  • Docs are pretty linear; sections do not compete with other to describe concepts
  • Diagrams to explain tricky flows
• Preact explains the whole API in a few pages; not sure if it it entirely what you need if you are a total beginner, but it's certainly digestable and links out to other content where needed.

Proposals

Move stuff here if it seems actionable

• Make home page examples into the first page of Getting Started, and remove code from below-the-fold section on homepage
• Add diagrams for component lifecycle/vdom sync. The community has already created lots of these for blog posts and talks; maybe one could be licensed for inclusion.
• Add a page that describes the motivation for the VDOM (ie, creating UIs that respond deterministically to data), and where the top-level React APIs (createElement, Element, render) fit into that model. This would help correct a "forest for the trees" problem where state and other APIs are introduced without broader context.
• Make API reference more prominent, at the same level as the Guide and Tutorial (PR #178)

Bắt đầu bằng việc xem xét các điểm truy cập hiện tại của trang chủ, Getting Started, Tutorial và tài liệu tham chiếu API, sau đó đối chiếu các đề xuất được liệt kê với kiến trúc thông tin hiện có. Công việc được xem là hoàn tất khi có một kế hoạch tái tổ chức đã được thống nhất và có thể triển khai; issue này không nêu các tệp, bài kiểm thử hay một thay đổi cụ thể cần triển khai.