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)

Inizia esaminando gli attuali punti di accesso alla homepage, a Getting Started, al Tutorial e alla documentazione di riferimento dell’API, quindi confronta le proposte elencate con l’architettura delle informazioni esistente. Il lavoro sarebbe completato quando fosse disponibile un piano di riorganizzazione concordato e attuabile; questo issue non indica file, test o una modifica specifica da implementare.