[New Docs] Wanted Guides

[gaearon]

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. Add Learning Resources section to the Community Resources on the website #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 React.cloneElement docs are a bit light #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)
• 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) Add guide on integrating with non-react code #9316 (review)
• ReactPerf should include a basic usage example, not just reference (Request: Better documentation of react-addons-perf #6174)
• Snapshot testing (Write documentation for react-test-renderer #7431)
• Publishing a Component (Docs request: build a React component library #7882)

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

[gaearon]

cc @lacker @hramos @ericnakagawa

[mrscobbler]

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]

I can possibly take routing with HTML5 history

[gaearon]

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]

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]

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]

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

[gaearon]

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]

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]

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]

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

[rthor]

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

[madhug]

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

[gaearon]

@madhug Assigned to you, thanks!

[jamesknelson]

@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]

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

[laumair]

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]

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

[neeharv]

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

[markerikson]

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]

@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]

@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]

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]

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

[gaearon]

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]

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]

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]

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:

1. 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)

2. 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.

3. 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.

4. ? 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?

[AlmeroSteyn]

I could also contribute to a section on Accessibility. Is anyone busy with this already? Are there any plans yet?

On that topic, the docs site itself has some accessibility issues that could be corrected easily. For a start, I have submitted #9431

[thamaranth]

What's still open?

[markerikson]

@thamaranth : based on the activity I've seen, probably anything in the first comment that's not checked off and doesn't have a name next to it.

[thamaranth]

I can help out with good resources if it's still open.

[akoserwal]

Hi @gaearon: is there anything remaining, which I can pick up?

[dance2die]

I'd love to contribute.
Would you assign me an issue I can get started with?
Thank you.

[markerikson]

@dance2die : I don't think anyone will "assign" you something - go ahead and pick something that looks good and go for it!

That said, this issue really should be migrated to the new docs site repo at https://github.com/reactjs/reactjs.org .

[bvaughn]

Migrated to reactjs/react.dev/issues/83

If you're interested in picking up any of these guides, let's talk on the new issue and I'll make them in-progress for you!