Docs nav is too noisy

[petehunt]

There's a lot of stuff in our left nav of the docs. It would be great if someone could clean this up and make it a little easier to digest.

[syranide]

👍

[sophiebits]

I sort of have a plan to rewrite and reorganize the docs… we'll see if I get the energy to execute on it.

[yoshuawuyts]

Take a look at the framer docs, what they've done with vertical breakpoints for the sidebar is remarkable.

[jefffriesen]

We built a live-filtering sidebar for our knowledge base. It's similar to how the 'Thinking in React' tutorial works (but did it before we knew about React). Maybe you don't want that much content shown initially, but you could still have a few topic areas exposed initially and then expose subtopics on filter.

[chenglou]

👍

[jstoja]

Is this still relevant ?

[chenglou]

Should have a revamp soon.

[AnSavvides]

Is this still an issue?

If so, I'd be happy to discuss how we could go about this in order to try and tackle it - easy to digest docs are key to getting people up and running & avoiding them thinking it's more complex than it actually is.

[syranide]

@AnSavvides If you ask me the doc is really confusing and cluttered :)

[syranide]

I remember there was a planned revamp being worked on though... not sure what happened to that.

[AnSavvides]

Ah I see - if there is a revamp in the works then that's great :)

Yeah, I think the hierarchy and structure needs a bit of love. The content itself is good, but knowing how to get to the right place for what you are after can be tricky, which usually means resolving to Google searches.

[joecritch]

Resurfacing this.

cc @zpao @spicyj

Here's a WIP diagram — https://coggle.it/diagram/VssL2FD-oEQ8IGQv/3e48c7aa04bffdbc88f610704de6779249eccd8217b5bc460741a8ff7cfc175b

---

Notes

• Concise terminology & tone-of-voice, so that developers can "learn" it and speak that same language, e.g. "composition, ecosystem", etc etc. (Taxonomy of web dev in general, not just limited to React)
• Separation of DOM vs. Custom components. From the point of view of a consuming developer, there's a lot of differences, even though they're all components.
• Tips could be in-context to the necessary categories or articles. They're currently unorganised.
• My next step on this will be matching up all the Jekyll pages precisely to these categories. But I'm pretty confident they'll fit.

---

Here's a rough outline for the "Guides" section based on the diagram. (I think anything covering the basics belongs in the Getting Started section) —

Docs

• Basics (prev. Quick Start)
  • Getting Started
  • Tutorial
  • Thinking in React
• DOM Components
  • Events
    • Synthetics
  • Styles
    • Inline styles
  • Forms
    • Controlled vs. uncontrolled
  • dangerouslyInnerSetHTML?
• Custom Components
  • Definition
    • ES6 vs. createClass
    • Stateless functions
    • Static methods
    • Autobinding
  • State [Take from "Interactivity and dynamic UIs"?]
  • Lifecycle
    • Rendering
    • Mounting / unmounting
    • getInitialState?
    • ref / key ?
  • Composition
    • Abstraction
    • Child components
    • Ownership
  • Validation
    • propTypes
    • Flow
  • Performance
    • Memoized renders / shallow compare
    • Immutability
    • Measurement API
  • Integration
    • DOM / other libraries
    • Web Components
• JSX ([Docs] JSX category #6101)
  • JSX Overview (prev. JSX In-Depth)
  • HTML Differences (prev. JSX Gotchas)
  • Conditional Statements (prev. if/else in JSX)
  • Spread Attributes

Community (#6099)

• Community
  • Support
  • Conferences
  • Videos
  • Complementary Tools
• More From Facebook
  • Flux
  • Relay
  • Immutable
  • Jest
  • Flow