[New Docs] Docs Bugs & Issues

[gaearon]

We just completely rewrote docs in #7864.
They're bound to cause some issues, have some mistakes, etc.
Let's keep this issue as an umbrella for all problems we're discovering after the initial rollout.

• Old links shouldn't be 404! Major issue.
• Topbar points to https://facebook.github.io/react/index.html which is ugly URL
• We shouldn't use Number as an identifier docs: list and key examples override Number #8034
• Remove vars everywhere except ES5 page
• JSX in depth has weird names like Story1, render2 @lacker
• JSX in depth shows a failing example with <hello> tag but doesn't show how to fix it @lacker
• Localized pages are gone: need to set up a new streamlined localization effort (cc @thejameskyle)
• Mention in default index.html that it is not production-ready
• Mark mockComponent as legacy and unnecessary
  Don't make mockComponent depend on Jest #2499 (comment)
• shallowCompare on Addons page should recommend PureComponent instead
• Figure out what to do with Community section ([Docs] Community section #6099)
• Mention string refs
• Forms doc has mistakes
• Forms doc uses setState for uncontrolled components which is confusing
• Installation is messy

[luqmaan]

Docs on Component API are 404ing: https://facebook.github.io/react/docs/component-specs.html#updating-componentwillreceiveprops

[gaearon]

Yea, something happened to all some redirects. @lacker

[gaearon]

@luqmaan Thanks, fixed. Let us know if you find more broken links.

[hzoo]

On Hello World, https://facebook.github.io/docs/installation.html should be https://facebook.github.io/react/docs/installation.html so the react/ isn't added and redirects to https://code.facebook.com/?

[Installation](/docs/installation.html) page

[johnbrett]

Great job on new docs all, love the live editor with error handling.

Just curious: Any reason why var is used on all the homepage tutorials? Curious whether there's a "best practice" on this.. would have thought const where possible, otherwise let?

[hzoo]

Another thing I noticed: this might of been an issue with the old docs but syntax errors don't have correct formatting of newlines from babel-code-frame

Someone can make a pr to add to add style={{whiteSpace: "pre-wrap"}} as a style on the div at

react/docs/_js/live_editor.js

Line 224 in eb118b7

<div className="playgroundError">{err.toString()}</div>,

or edit the .playgroundError css class in https://github.com/facebook/react/blob/15-dev/docs/css/react.scss (<pre> seems to make it go over the width limit of the colored error box)

Width would need to be longer to be accurate but it would be better than before

[gaearon]

Any reason why var is used on all the homepage tutorials?

No reason, feel free to send a PR fixing this.

[pythononwheels]

If this is the "new style" I think you should point out the key differences to the "old style".
Just to take people with you.... knowing what key things change and why ...

[gaearon]

Does it matter at this point? It's not as much style as a lack of cohesion in previous docs.

They weren't really grouped by topic, there was no clear progression from simple to complex, their titles weren't descriptive, there were many random "tips" that didn't fit a cohesive narrative, they were using APIs that aren't used widely in the ecosystem anymore, etc.

New docs are in line with how people use React today, have descriptive titles, and a linear progression from simple to more complex topics.

That's the basic difference.

[p-adams]

Possible typo in docs: "Consider the ticking clock example from the one of the previous sections."

https://facebook.github.io/react/docs/state-and-lifecycle.html

[hnordt]

@gaearon the uncontrolled form example on https://facebook.github.io/react/docs/forms.html#uncontrolled-components is passing value, so it's actually a controlled example.

The correct example would be something like:

class Form extends React.Component {
  constructor(props) {
    super(props);
    this.handleSubmit = this.handleSubmit.bind(this);
  }

  handleSubmit(event) {
    alert("Text field value is: '" + this.textInput.value + "'");
  }

  render() {
    return (
      <div>
        <input
          type="text"
          placeholder="Hello!"
          ref={(input) => this.textInput = input}
        />
        <button onClick={this.handleSubmit}>Submit</button>
      </div>
    );
  }
}

ReactDOM.render(<Form />, document.getElementById('root'));

[giuseppeg]

A controlled component does not maintain its own internal state; the component renders purely based on props.

• is a bit confusing, probably better clarify that we are talking about DOM state instead of React state.

---

• In thinking-in-react.html#step-4-identify-where-your-state-should-live the second last paragraph shouldn't mention getInitialState()

---

• In jsx-in-depth.html#javascript-expressions there are two headings with the same ID "JavaScript Expressions" - this makes it impossible to link to the second one.
• The fourth example in the innermost one is missing props.:

// Calls the children callback numTimes to produce a repeated component
function Repeat(props) {
  var items = [];
  for (var i = 0; i < numTimes; i++) {
  // ... 
}

Here numTimes should be props.numTimes.

[Andreyco]

Why was info about latest stable removed from landing page?