High-level reorganization

[alexkrolick]

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 Add top level API link to header nav #178)

[bvaughn]

Make home page examples into the first page of Getting Started, and remove code from below-the-fold section on homepage

This is probably more work than it sounds like. (I'm not saying it's not the right move, just wanted to point that out.) It would require us to write a new custom Remark plug-in that could generate the runnable code examples- in a way that's optimized to defer loading JS-heavy things like Babel on pages that didn't need them.

[alexkrolick]

Hmm. Do we have analytics on how many people actually edit the live code samples on the front page? Maybe they don't need to be live. Pure speculation.

[bvaughn]

I think the gatsby-remark-code-repls we recently released could help a bit with this, since it would let us easy generate links to try things out in eg CodePe- but I still think the live, "see it in action and try it yourself" experience is important. And even though it adds weight (in terms of downloaded JS libs) to the home page, I also think it's nice to have as an experience that greets you right away.

I'd like to know what others think about this though.

[markerikson]

tagging @gaearon , since he was just asking about ways to improve the docs organization.

[gaearon]

Can you expand on your tweet? I'm not sure I'm catching what you mean by lack of ordering. I think the order is pretty clear: Quick Start, then Advanced Guides, then maybe API Reference if you need it.

[markerikson]

Pasting in my tweet reply:

• There's both a "Getting Started" section and a "Tutorial" section. It's not clear how they relate to each other conceptually.
• While that list might be in "an" order, it's not immediately obvious it's a step-by-step thing
• "Advanced Guides" has a hodgepodge of random info. It would be helpful if this was maybe further grouped into subcategories. Hypothetical-ish example:

• React Concepts In Depth
  • JSX In Depth
  • Reconciliation
  • Fragments
  • Type-Checking with PropTypes
• Working with the DOM
  • Uncontrolled Components
  • Refs
  • Forwarding Refs
  • Portals
  • Integration with Other Libraries
  • Web Components
• Component Patterns
  • Context
  • Higher-Order Components
  • Render Props
• Optimizing Applications
  • Optimizing Performance
  • Code Splitting

[gaearon]

"Quick Start" should really be called something like "Introduction to Concepts". But preferably shorter. Ideas?

[gaearon]

I like your grouping for the advanced section btw. But I don't think we currently go deeper than one top-level group. Would this need a sidebar redesign?

[markerikson]

Assuming you wanted to keep the current sidebar groupings, then yes.

[alexkrolick]

I like those groupings as well.

Can probably piggy back on the sidebar changes in #949 to add support for more nesting.

[alexkrolick]

What do you think of moving 3. Rendering Elements in front of 2. Introducing JSX, or pulling JSX into an Advanced Guide? Reading through the tutorial from the beginning, it seems like rendering elements is the most natural entry point and syntax can be explained later.

[gaearon]

I'm pretty hesitant. I don't think you can read the guide very well if you don't understand what { and } mean, or that those are not HTML strings.