Getting new-docs ready for launch

[lacker]

This is just cleaning up a bunch of little loose ends left over. I think this is the last stuff we need before merging new-docs to master.

• Adds redirects for all the broken links (that I could find manually)
• Rename the tutorial so only one thing is called "Thinking In React"
• Made sure prev/next links are correct for the quickstart
• Fix left nav spacing
• Get rid of all the unused stuff marked "old" like yml config template etc
• Make sure the error decoder still works

[gaearon]

Shouldn't Addons be part of the Reference rather than Advanced Guides?

[AndrewIngram]

My initial thought is that the installation page throws a lot of concepts at you. A lot of stuff is mentioned before I even find out the names of the npm packages to install. It feels like you're trying to cover all bases by catering to every possible audience, but that makes it harder to pull out the information relevant to me. Are we installing a library or introducing an entire development paradigm?

Perhaps a more appropriate starting point might be to divide and conquer the audience based on what they're trying to achieve (your page headings do this to a degree, but I don't think it's enough):

1. I just want to install React into my project (npm, yarn or script tag)
2. I just want to play with the API in a sandbox
3. I want to introduce React into an existing codebase
4. I want to build a new single-page application (information about create-react-app, along with anything else that supports this)
5. I want to learn about complementary tools (redux, mobx, react-router, webpack, babel, etc)

[gaearon]

Can you clarify this please?

Perhaps a more appropriate starting point might be to divide and conquer the audience based on what they're trying to achieve

I think that’s exactly what we tried to do. If it doesn’t work, could you please submit a PR against next-docs branch showing your proposal?

[jquense]

The "React without es6" bit feels a bit weird to me. If starting fresh why show folks createClass instead of the actual es5 analog to the class syntax used in the docs everywhere else. It introduces a magical class abstraction that has a lot more then the JS "classes", when the user will likely be more familiar with the old school constructor function pattern, plus you still to the "use the language" position React takes in most other places. Plus you don't encourage use of something you want to deprecate eventually just b/c folks don't want to transpile their code.

[gaearon]

We can't just omit createClass completely, a ton of online content uses this pattern, and will use for a while. At this point retrofitting function X() and X.prototype.render will be weird because nobody in the wild uses this pattern.

[AndrewIngram]

@gaearon what I'm getting at is that by reading just the installation page, here's a list of terms and technologies i'm potentially coming across for the first time:

1. CodePen
2. runtime code transformation
3. Single Page Application
4. Create React App
5. frontend build pipeline
6. Webpack
7. Babel
8. ESLint
9. npm
10. bundler
11. Browserify
12. react-dom?
13. transpiling
14. es2015 and react presets?
15. production mode?
16. Bower
17. ES6
18. JSX
19. babel-preset-react and babel-preset-2015, is that different to those earlier presets?
20. .babelrc?
21. CDN?
22. UMD?
23. dist folders?

[gaearon]

Would you like to submit a PR to make it more friendly? This section was written in a bit of a haste and I agree it would benefit from a more introductory perspective. The constraint is that all those details still need to live somewhere.

[AndrewIngram]

I'll need to think about the problem a bit more, I don't have the full context of what this rewrite is attempting to solve.

Train of thought alert:

My main thinking is that React's sweet spot (when viewed as a standalone library) is still as a tool for adding rich interactivity to existing applications in a maintainable manner. Absolute newcomers to React are going to have the best time if this is what they're trying to do, and it should be possible to explain how to get up and running with a relatively constrained amount of jargon.

Obviously React now has a huge ecosystem and people are trying to use it for much more, and I think Create React App is a great introduction. But educating people on that is a much bigger can of worms, and one that I think should be handled as a page or section in its own right.

[gaearon]

I don't have the full context of what this rewrite is attempting to solve.

Curious if you had a chance to look through other pages yet? Mostly we are trying to provide a step-by-step introduction to concepts, from simpler to more complex, instead of mashing them all together without a specific order, like in current docs.

[AndrewIngram]

I had a brief look and the rest of it does feel like a more gentle introduction, it's mainly just the installation page that feels overwhelming.

[gaearon]

@lacker I'm working on PR against this that splits conditional & lists guides and adds some more content to them.

[gaearon]

lacker#2

[gaearon]

Shouldn't these two pages point to Installation instead?
They were about setting up build transforms, not about createClass().

[lacker]

ok

[gaearon]

If/else should link to "Conditional Rendering" instead. I added it as a separate guide in lacker#2.

[lacker]

ok

[gaearon]

This is unfortunate. We don't have a good place for "Fetching Data", and we removed the only example we had about it.

[lacker]

Yeah, it's just a redirect though. I think the world will survive having one "tip" with ~0 usage having a confusing redirect.

[gaearon]

I'm worried this might be linked to from StackOverflow, e.g. "here's how to do AJAX in React". Can't prove it tho.

[gaearon]

So is this. Maybe let's make it link to ref doc instead.

[lacker]

This tip only did one thing, gave an example of a component with all the lifecycle methods doing nothing. So I think this is the logical place to redirect it to, also the tip was not really too helpful for anything IMO.

[lacker]

OK I responded to every detailed item. I think the main open question is whether we should muck around with the "installation" flow or just leave it as is.

[gaearon]

I'd say ship now and we can fix it up later.

[lacker]

Well I fixed it up :P @AndrewIngram I think it will be simpler here since the initial flow goes to "hello world" which just suggests codepen. Last call for feedback here.

[JamieDixon]

Thanks for the great work on these docs, they're really great.

One thing I might adjust is the hello world codepen linked to at the very start (http://codepen.io/gaearon/pen/rrpgNB?editors=0010).

If as I complete beginner I were to add a <p>Does this work?</p> under the existing <h1> I might be confused to discover that nothing happens. If I'm familiar with codepen I might notice the tiny red circle over on the other side of the screen but if not, I might just be confused and give up.

We could instead wrap the current <h1> in a container (<div> perhaps) to make it clearer that new stuff needs to go inside a root element.

ReactDOM.render(
  <div>
     <h1>Hello, world!</h1>
  </div>,
  document.getElementById('root')
);