[New Docs] Wanted Guides

gaearon commented 8 years ago

We revamped the docs, but there are a few guides that are missing and that I think are essential.

[ ] Community section with good resources (e.g. https://github.com/facebook/react/pull/7117)
[ ] @mrscobbler Glossary (similar to "Virtual DOM Terminology" that is now gone, but more friendly. Check http://redux.js.org/docs/Glossary.html for inspiration.)
[ ] Troubleshooting (there are ~5 common issues we should explain right away, like wrong element casing, not loaded DOM container, missing React in scope, etc. See http://redux.js.org/docs/Troubleshooting.html for inspiration)
[ ] Accessibility
[ ] @madhug Manipulating Children (Using cloneElement and Children https://github.com/facebook/react/issues/6942)
[ ] "Portals" (useful for modals)
[ ] Animation with React Motion
[ ] @jamesknelson Routing (no need to use React Router here, just show how to use setState with HTML5 history API and point to RR as a component-based API for it once v4 is out)
[ ] AJAX (just show how to use fetch() in lifecycles, mention cancellation issues)
[x] Integrating with non-React code (show how to wrap jQuery plugin in React, how to expose React component as a Backbone view, and how to consume Backbone models) https://github.com/facebook/react/pull/9316#pullrequestreview-30403084
[ ] ReactPerf should include a basic usage example, not just reference (https://github.com/facebook/react/issues/6174)
[ ] Snapshot testing (https://github.com/facebook/react/issues/7431)
[ ] Publishing a Component (https://github.com/facebook/react/issues/7882)

If somebody wants to work on this please comment here and let's figure out a plan. Help wanted!

gaearon commented 8 years ago

cc @lacker @hramos @ericnakagawa

mrscobbler commented 8 years ago

I'll take the glossary sections. Is there a list of terms somewhere I can work of off? Or should I come up with some? I don't remember what the virtual DOM terminology page contained.

jamesknelson commented 8 years ago

I can possibly take routing with HTML5 history

gaearon commented 8 years ago

Regarding terminology, please assume familiarity with all topics in "Basic Guides". Most of them have relevant terms right in titles (elements, components, props, state, lifecycle, events, keys).

jamesknelson commented 8 years ago

Does the routing guide even need to use setState? I think it should be possible to do with plain props. Also, will hash-based routing be OK? If not, it'll probably need context to make a <Link> component work which seems a little complicated.

gaearon commented 8 years ago

If we do plain props we'll have to make top level render inside a change handler right? I'd like to avoid that because people often don't understand how to compose two such handlers.

I think we should teach HTML5 routing right away. Like here: https://vuejs.org/guide/routing.html. Would you really need context? You can have Link listen to history independently.

jamesknelson commented 8 years ago

Actually, it shouldn't need context if we're just using plain HTML5 history. I was thinking of using the history package.

gaearon commented 8 years ago

I want to keep it package free so people see the simplicity of doing routing with React, and then go to packages when they actually need their features.

jamesknelson commented 8 years ago

Yes, that is the definitely ideal. Was a thinking mistake on my part.

So just to confirm, the idea is to add a listener in componentWillMount of a Router component, use setState based on that, then choose what to render based on state? Then create a Link component which captures onClick and does pushState?

gaearon commented 8 years ago

Maybe not even call it Router, just make a top level App component choose the right thing based on state and a URL => component map object or something like that.

jamesknelson commented 8 years ago

Ok. Will put a draft together probably this weekend :)

rthor commented 8 years ago

I'm writing a guide on ajax. Is that good with people or is someone already on it?

madhug commented 8 years ago

Is anyone working on Manipulating Children #6942 or can I take it?

gaearon commented 8 years ago

@madhug Assigned to you, thanks!

jamesknelson commented 8 years ago

@gaearon I've started putting the routing guide together, but the HTML5 History API is a little less nice than I had imagined.

First, browser's don't emit the popstate event when pushState is called. This means <Link> components will need some way of notifying the <App> component of any changes -- e.g. context or a shared global. Second, Safari doesn't emit popstate on page load, while other browsers do.

While I have no problem with explaining these things, it would end up being a guide to HTML5 History instead of a guide to React Routing. Would it be ok to use the hashchange event instead, or possibly history?

Also should I create a separate issue for this?

gaearon commented 8 years ago

OK, using history seems reasonable with a note that it hides browser inconsistencies.

laumair commented 8 years ago

Is anyone working on AJAX (just show how to use fetch() in lifecycles, mention cancellation issues). I'd like to take this on. I might have a few questions though before getting started.

rthor commented 8 years ago

Yeah, been working on it (#8098). Just awaiting final review. Any news on getting it merged @gaearon ? :p

laumair commented 8 years ago

@rthor Ah, okay. Is there any other stuff that's left from the checklist?

brillout commented 8 years ago

I maintain a catalog of components/libraries: brillout/awesome-react-components / devarchy.com/react-components. Maybe it could make sense to mention the catalog in the doc?

laumair commented 8 years ago

@gaearon Is there any item from the checklist that isn't occupied atm?

mrscobbler commented 8 years ago

Created a pull request for a glossary of terms: https://github.com/facebook/react/pull/8199

Would love some feedback on it.

dhyey35 commented 8 years ago

Can I take ReactPerf should include a basic usage example, not just reference (#6174) or is anybody already on it ?

dhyey35 commented 8 years ago

@laumair I think Animation with React Motion and last two ( snapshot and publishing ) are yet to be taken as no comments on them.

laumair commented 8 years ago

I think I can take publishing

hedgerh commented 8 years ago

I have some thoughts regarding the "community resources section" document.

I think we should compile resources that newcomers aren't going to already come across after a couple of random Google searches. Rather than "Getting Started With React" tutorials, or React video courses, I'd like to point people to communities like Reactiflux and #reactjs on IRC, which have been invaluable to me.

I'd like to point people to blog posts/articles that cause light bulbs to go off when they read them. Dan, your post on smart/dumb containers is pretty quintessential reading for newcomers at this point. Also, resources that cover things like how it's a better pattern to pass each prop a component needs individually <Post title={postObject.title} author={postObject.author}/>, than to pass a whole data object down as a single prop <Post post={postObject}/>.

Beyond that, I think we should guide them to any other places in the community where they can find good resources on their own.

lacker commented 8 years ago

@hedgerh That sounds good overall - although I think we should only really remove stuff that we believe is lower quality than a random Google search and therefore we do not recommend, rather than removing stuff that we theorize newcomers will come across while Googling. It's still helpful to say "we believe this is the best few video courses out there".

hedgerh commented 8 years ago

@lacker - good point. i'm totally cool with that as long as it doesn't become a link dump.

brigand commented 7 years ago

I'm working on "Publishing a Component". https://github.com/facebook/react/pull/8427

vaskort commented 7 years ago

Hello! New to React but I feel I could contribute to the accessibility guide, can you tell me roughly what would you like to see in the accessibility guide @gaearon?

ConAntonakos commented 7 years ago

Would love to finally contribute! It seems that portals and snapshot testing are available. I've recently been delving into portals, modals, and react-overlays, so I'd love to jump on that.

For snapshot testing, do we want to talk about https://facebook.github.io/jest/docs/tutorial-react.html#snapshot-testing?

mtomcal commented 7 years ago

Can I work on "Integrating with non-React code (show how to wrap jQuery plugin in React, how to expose React component as a Backbone view, and how to consume Backbone models)" @gaearon ? I've had to do this a few times for jQuery and I used to do Backbone and use it there as well. Doing also how to use React Components with Angular (just the basics) would be fun.

markerikson commented 7 years ago

Some interesting points in an HN discussion thread on a desire to have the official React docs either include more "official" info on application-wide topics like routing, or at least point to vetted sources beyond the docs: https://news.ycombinator.com/item?id=13374170

markerikson commented 7 years ago

As a related note, the Reactiflux website is being revamped and should be ready shortly. As part of that, I did a sweep through my React/Redux links list, picked out the top two or three articles in several key categories, and that shortened list is being added to a "Learning" page on the Reactiflux site. The current version of that page is at https://github.com/reactiflux/reactiflux.com/blob/master/pages/learning.md . That would be a good resource to link from the React docs, or maybe even copy over / cherry-pick from?

@gabegreenberg , any thoughts on this topic?

frederikcreemers commented 7 years ago

It's still a WIP, but it might be useful to mention react-a11y in the accessibility guide.

neeharv commented 7 years ago

@gaearon should this also include a section for code splitting? Happy to help with that.

markerikson commented 7 years ago

So what are the current thoughts on a "Learning Resources" section? Per the list, @tylermcginnis proposed one over in #7117 , and that was closed due to the docs rewrite.

I know I've seen a lot of people complain that the React docs don't tell you how to build a full-blown app. I agree that the core of the docs should focus on React itself, especially given the variety of ways that people use React, but at a minimum a pointer to additional resources would be good.

I'm very biased, but my React/Redux links list actually covers several of the topics listed here. For example, it has sections discussing use of `children, rendering modals, wrapping non-React code like jQuery plugins, making AJAX calls, performance and optimization, and much much more.

Also, per my comment earlier: I put together a "best-of / guided learning" version of my links list for the new Reactiflux site at https://www.reactiflux.com/learning/ , and later updated the front page of my list to show that.

So, while it wouldn't be bad to have some of those topics directly in the docs, there's enough good quality articles out there already that I think the docs could simply point to a couple selected articles on each of these topics, and then maybe point to my list and Tim Arney's React FAQ as sources for further information.

pinakdas163 commented 7 years ago

@gaearon I want to work on this doc: Troubleshooting (there are ~5 common issues we should explain right away, like wrong element casing, not loaded DOM container, missing React in scope, etc. See http://redux.js.org/docs/Troubleshooting.html for inspiration)

Is it still open for contribution?

lacker commented 7 years ago

@pinakdas163 I think a "troubleshooting" doc is often not a good idea when the topic is very broad like "everything about React". It's very hard for the core team to keep it up to date, since there's no good way of detecting when particular troubles are later resolved. And it's also hard for people to find, since you rarely are debugging your troubles by searching for a "troubleshooting" doc on the React website. Instead, when there are common issues that lead to people finding a bug and then fixing it, people are more likely to look somewhere like Stack Overflow, or to search and find a heavily-SEO'd site like Stack Overflow. So my suggestion would be when you run into troubleshooting-type troubles, to try to put them in Stack Overflow rather than into the React docs. If there were a more specific troubleshooting section like "troubleshooting when using web components" then it might be very useful to put that in existing guide pages.

gaearon commented 7 years ago

I don’t know.. In my experience Troubleshooting doc (at least in Redux) was incredibly helpful in fixing 50% of most commonly asked questions.

I think it would be a huge win to have it in React even if it documents just:

Promises swallowing errors inside setState (solution: use catch carefully)
this.state not updating right after setState (solution: use setState updater overload)
this being undefined (solution: use arrows, bind, or property initializers)

lacker commented 7 years ago

OK, those sound like a pretty interesting list of things to read through linearly actually.

gaearon commented 7 years ago

This is also a good candidate for Troubleshooting. Basically, "why doesn't my state update" often comes from data derived in the wrong place (especially from props). This used to be in the old docs but we yanked it.

dmitriid commented 7 years ago

Animation with React Motion

Perhaps, animation in general? This is a broad topic, and many parts are very hard to implement with React (at a first glance).

Some of the problems I've run into:

Due to reconciliation, it's hard/impossible/very-hard-to-control to:

animate the removal of a component
animate removal/changing/reordering of list animations
animate changes in components that reuse underlying DOM structure

There are undoubtedly others. Re-parenting is quite often mentioned on twitter.

Just to give a quick example. I'll keep components stateless for clarity of code.

// app.jsx

let observableState = 'login'

const LoginForm = () => {
  return <form>
     <label>Login</label> <input name="login" />
     <label>Password</label> <input name="password" />
     <button onClick={login}>Login</button>
     <button onClick={() => observableState = 'signup' }>Sign Up</button>
  </form>
}

const RegisterForm = () => {
  return <form>
     <label>Login</label> <input name="login" />
     <label>Password</label> <input name="password" />
     <label>Access code</label> <input name="code" />
     <button onClick={signup}>Sign Up</button>
     <button onClick={() => observableState = 'login' }>Login</button>
  </form>
}

const App = () => {
  if(observableState === 'login') {
    return <LoginForm />
  } else if(observableState === 'signup') {
    return <Signup />
  }
}

React.render(<App />, ...)

When switching between forms, React will only:

remove/add "Access code"
update button text and handlers

So, there are quite a few questions about animating all this:

Animate one form disappearing, another appearing? Rely on componentWillReceiveProps and handle this through props?
Animate Access Code disappearing, then appearing when switching forms? There's no controlled onRemove to animate the removal of the component. Moreover, if <Login /> sprouts a third input, Access Code will no longer be removed/added, but only updated, like the rest of the elements
etc. etc.

If anyone figured this stuff out, it would be a great service to the community to describe how to deal with these and other situations in React (an to a larger community as a whole, because this same problem exists in all similar frameworks: snabbdom, virtual-dom, inferno ... )

dmitriid commented 7 years ago

no need to use React Router here, just show how to use setState with HTML5 history API and point to RR as a component-based API for it once v4 is out

This might generate some backlash from the community. The name React Router implies it's directly endorsed and/or supported by the React team. However:

it's not
by version 4 it's now had 4 major backwards incompatible changes in the API, leaving many developers hanging. (I can't find a big discussion about it right now, it may have been cleaned up to keep it more civil)

UPD: Editing this issue to add more context and to bring it in line with my comments on the documentation review

There are more routing libraries than just React Router
is known to introduce major breaking changes with no deprecation policy
promotes bad coding practices (see this issue, for example)
has had multiple unaddressed issues in the past that were ignored despite active community requests (search for "named routes", probably starting as early as here, linked issues are also worth a read). And definitely this

igolden commented 7 years ago

Is anyone assigned Snapshot testing yet? I think it's a crucial guide to help take new React devs from "Hello World" React and into production, I'd love to take that doc if no one is on it yet.

After looking at #7431, my outline is:

Give a conceptual intro to snapshot testing, followed by a simple react-test-renderer example. In particular, using components from the React docs (Forms, Lists for example)

Follow that up with a simple example testing refs with a callback (issue), maybe with the example components above. That seems to be the first thing people hang up on with snapshot tests.
Then illustrate a real-world snapshot test example with mocks using Jest. This would be an area to address the ReactDOM issue and also point people in the direction of Jest as a test framework.
? I'd be happy to cover shallow-render example too, with Enzyme or ReactTestUtils, but we could point them to the Jest docs for that. My inclination is to include that info in React docs, because shallow-rendering is already documented and Jest is supported by FB.

Am I missing anything?