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)

Start by reviewing the current homepage, Getting Started, Tutorial, and API reference entry points, then compare the listed proposals with the existing information architecture. Done would require an agreed, actionable reorganization plan; this issue does not name files, tests, or a specific change to implement.