Break out Installation into top-level doc section #452

alexkrolick · 2017-12-20T23:53:49Z

No more jumping over the installation section with links pointing to the "first" Quick Start page
Get rid of some of that custom footer code that hardcodes "installation" as a special case
Installation is important, may as well have its own section 😛

reactjs-bot · 2017-12-20T23:57:16Z

Deploy preview ready!

Built with commit bcf3a5b

https://deploy-preview-452--reactjs.netlify.com

bvaughn

I think I like this change, in general.

It feels odd though for "Installation" to come after "Quick Start".

"Quick Start > Hello World" mentions that you can use React from CodePen without installing anything, but then again so does the first page of the new "Installation" section.

I think maybe "Installation" might make more sense to come first but...I'm not positive.

bvaughn · 2017-12-22T01:14:34Z

content/docs/installation-try-react.md

+  - "docs/environments.html"
+---
+
+React is flexible and can be used in a variety of projects. You can create new apps with it, but you can also gradually introduce it into an existing codebase without doing a rewrite.


I'm not sure this lead paragraph (and the below header) make sense anymore, given what this page has been remade into.

Maybe we should rename the page title to something like "Try it on CodePen" and leave out this paragraph entirely?

Sure, although, how about adding more than Codepen? The Codesandbox template for React is pretty mature and quite popular, and we could link out to other content like the editable examples on the home page.

Sure. That'd be totally fine. CodeSandbox comes to mind as another excellent solution.

bvaughn · 2017-12-22T01:15:21Z

content/docs/installation-try-react.md

+  - "docs/tooling-integration.html"
+  - "docs/package-management.html"
+  - "docs/language-tooling.html"
+  - "docs/environments.html"


The new Installation pages should have prev/next frontmatter links 😄

See #451 - the lack of sync between the titles and the ids causes the next/prev to appear as "Installation New Apps", etc

Not sure I understand. The next/prev titles are currently generated based on the URL you put in the next/prev frontmatter (so it's something we control, even if it's not synced).

I think the new section should still have next/prev links to feel more consistent with the others.

// installation-existing-app.md id: installation-existing-app title: Add React to an Existing Application

// elsewhere next: installation-existing-app.html

Results in:

Instead of:

This is because of #451 where the url is parsed instead of looking up the title in the TOC data structure. I am planning on fixing that and adding next/prev once it is done, but I can certainly adjust the filenames for now so that it looks correct (I want to change it back long term so that all the related filenames start with installation as has been done with faq and other sections).

EDIT: it's actually the filename, not the ID, that is the problem, although they are usually the same.

so it's something we control, even if it's not synced

You chose to name the new file installation-existing-app.md. So I'm just saying, before #451 is resolved, we could work around this issue by just naming it add-react-to-an-existing-app.md instead. 😄

alexkrolick · 2017-12-22T01:43:19Z

It feels odd though for "Installation" to come after "Quick Start".

Yeah, a little, but it does feel a bit weird that lots of links to Quick Start appear to be skipping a section if that's where you land from the home page.

bvaughn · 2017-12-22T18:14:59Z

I think that's okay, or at least preferable to this. I wonder if people actively look for installation- they'll expect it to come first (and may miss it entirely if it's collapsed below an expanded list of items.)

- Move Installation section to top - Add next/prev to install pages

gaearon · 2017-12-22T20:48:46Z

content/docs/try-react.md

+
+If you're just interested in playing around with React, you can use CodePen. Try starting from [this Hello World example code](http://codepen.io/gaearon/pen/rrpgNB?editors=0010). You don't need to install anything; you can just modify the code and see if it works.
+
+If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production.


I think we should add a section here that points to the next two sections and explains in which case you'll want which. It's too easy to miss them otherwise.

Working on this 😛

Pushed a change - added "Local Development" section to the Try React page

alexkrolick · 2017-12-22T21:27:08Z

@bvaughn

Moved Installation to top
Added prev/next by changing filenames
Added Codesandbox

@gaearon

Reorganized and added links to the other install guides

gaearon · 2017-12-22T21:36:49Z

content/docs/try-react.md

+
+## Install React
+
+- **[Add React to a New App](/docs/add-react-to-a-new-app.html)** Create a new app with a starter kit like [Create React App].(http://github.com/facebookincubator/create-react-app)


The link Markdown is broken

gaearon · 2017-12-22T21:37:23Z

content/docs/try-react.md

+
+If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production.
+
+## Install React


This makes it sound like it's part of this page. IMO this makes it worse. I was thinking something that more obviously implies it's an optional next step, not something you have to do.

gaearon · 2017-12-22T21:37:41Z

content/docs/try-react.md

+## Install React
+
+- **[Add React to a New App](/docs/add-react-to-a-new-app.html)** Create a new app with a starter kit like [Create React App].(http://github.com/facebookincubator/create-react-app)
+- **[Add React to an Existing App](/docs/add-react-to-a-new-app.html)** _Advanced configuration._ Use React with a build system like Webpack.


I don't think this description is very helpful.

I'm not sure the dichotomy is correct here - "Add React to A New App" links to CRA primarily, and "Existing App" is all about build systems and CDN links. It makes sense to promote CRA as the starting point, but I think it is confusing to talk about the next page as only for existing apps. It's more of an advanced guide, or maybe a bundling/build guide. The CDN links could also probably be more prominent, with the caveat that they aren't very useful without Babel.

What do you think?

I understand what you're saying. My point is just that

Advanced configuration. Use React with a build system like Webpack.

is not very meaningful to someone visiting the page for the first time. What advanced configuration? What is webpack? Does the first link not use webpack? etc I'm open to other phrasings of the same idea, this sentence just read as confusing to me.

I think it is confusing to talk about the next page as only for existing apps

In a way, yes. But on the other hand it provides a clear entry point for each use case. If you're ready to configure things on your own you already know enough that you don't need either of these sections.

Just changed the description to "Add React to a build system or larger app." --- how does that sound? Can iterate on the naming of the page later.

Also added a "Next Steps" header above the Quick Start and Install sections to make it clear that those aren't part of Trying React, but ideas for what to do next if you're set up.

gaearon · 2017-12-22T22:54:57Z

content/docs/try-react.md

+
+### Quick Start
+
+Head over to the [Quick Start](/docs/hello-world.html) section to try some examples.


I think it's a bit misleading to call QS section that (since it doesn't have that many useful "examples").

Maybe it would be better to direct people either to Tutorial (for those looking for a hands-on practical introduction) or to QS (but frame it as a step-by-step introduction to React concepts).

Linking to the Tutorial is a great idea --- I'll use that exact phrasing actually.

gaearon · 2017-12-22T22:55:19Z

I'm really liking these changes. Left one last nit I have.

This is useful for Codepen and other Unpkg-y setups

alexkrolick · 2017-12-23T00:34:58Z

Pulled CDN links to the top level
Added link to tutorial page

Care to take one more pass?

😄

gaearon · 2017-12-23T00:39:45Z

content/docs/try-react.md

+  - "docs/environments.html"
+---
+
+Try React online or set up your local dev environment


"development environment"

Also let's end with period like we do elsewhere?

gaearon · 2017-12-23T00:42:55Z

content/docs/try-react.md

+
+If you're just interested in playing around with React, you can use an online code playground. Try a Hello World template on [CodePen](codepen://hello-world) or [CodeSandbox](https://codesandbox.io/s).
+
+## HTML Template


Maybe "Minimal HTML Template" to make it clearer what this is about

gaearon · 2017-12-23T00:47:45Z

content/docs/try-react.md

+
+- Try the [Tutorial](/tutorial/tutorial.html) for a hands-on practical example.
+
+### Install React


Again, this sounds like it's a required step because of the title.

How about: "Powerful Development Environment" or "Complete Development Environment". Maybe also change the sentence to explain when/why you'd want that.

The goal is to explain this step takes time but gives you a great developer experience and a production-ready setup with linting, testing, and optimizations built-in. We have a chance to preempt "omg why is it 100mb" knee-jerk responses here by being explicit that it's not just for 'hello world' but more IDE-like.

gaearon · 2017-12-23T00:49:35Z

content/docs/add-react-to-a-new-app.md

+next: add-react-to-an-existing-app.html
+---
+
+The easiest way to get started on a new React project is by using a starter kit.


Related to https://github.com/reactjs/reactjs.org/pull/452/files#r158572397: maybe it's worth pointing people looking for something lightweight to "Try React" from this page. I'd love if we could make it clearer that this is a fully-featured setup that isn't required for using React but covers common needs for a single-page application including linting, testing, optimizations, etc.

👍 Added a note here

gaearon · 2017-12-23T15:37:46Z

I think this is great! Hopefully nothing breaks 😄
Thank you so much for reorganizing this!

facebook-github-bot added the CLA Signed label Dec 20, 2017

Break out Installation into top-level doc section

bee089a

alexkrolick force-pushed the top-level-installation-guide branch from 6ed168f to bee089a Compare December 21, 2017 01:05

bvaughn reviewed Dec 22, 2017

View reviewed changes

Update navigation (prev/next, nav tree)

e87ec4f

- Move Installation section to top - Add next/prev to install pages

gaearon reviewed Dec 22, 2017

View reviewed changes

add links to other install options from try react page

451ca08

gaearon reviewed Dec 22, 2017

View reviewed changes

alexkrolick added 2 commits December 22, 2017 12:52

fix markdown link

fa8d576

Clarify that Quick Start and Install are optional "next steps"

2365e37

gaearon reviewed Dec 22, 2017

View reviewed changes

alexkrolick added 3 commits December 22, 2017 13:58

Add top-level CDN page

289bd7e

This is useful for Codepen and other Unpkg-y setups

Add link to Tutorial from Try React

4ed0bad

Update CRA link in tutorial

2c65291

alexkrolick force-pushed the top-level-installation-guide branch from 3d06b4e to 2c65291 Compare December 22, 2017 23:09

gaearon reviewed Dec 23, 2017

View reviewed changes

Make Try React subheader a proper sentence

6ab880a

gaearon reviewed Dec 23, 2017

View reviewed changes

alexkrolick and others added 5 commits December 22, 2017 17:55

Add "minimal"

a3fd8b4

Explain local dev setup is more work than Codepen etc

32299c4

Fix typos

29382bb

Add : between headings

1df722c

add note that CRA is not lightweight

b9e6eab

alexkrolick and others added 7 commits December 23, 2017 00:28

fix typo

c76df53

Update add-react-to-a-new-app.md

b7159cf

Update add-react-to-a-new-app.md

9975cfa

Remove the Bower note

e1c2df4

Update try-react.md

9ce4233

Tweak wording

e332245

Use direct link

bcf3a5b

gaearon merged commit 7fafb9f into reactjs:master Dec 23, 2017

BetterZxx pushed a commit to BetterZxx/react.dev that referenced this pull request Mar 21, 2023

docs(cn): fix survey banner (reactjs#452)

9775b4c


		If you're just interested in playing around with React, you can use CodePen. Try starting from [this Hello World example code](http://codepen.io/gaearon/pen/rrpgNB?editors=0010). You don't need to install anything; you can just modify the code and see if it works.

		If you prefer to use your own text editor, you can also [download this HTML file](https://raw.githubusercontent.com/reactjs/reactjs.org/master/static/html/single-file-example.html), edit it, and open it from the local filesystem in your browser. It does a slow runtime code transformation, so don't use it in production.


		## Install React

		- [Add React to a New App](/docs/add-react-to-a-new-app.html) Create a new app with a starter kit like [Create React App].(http://github.com/facebookincubator/create-react-app)


		### Quick Start

		Head over to the [Quick Start](/docs/hello-world.html) section to try some examples.


		If you're just interested in playing around with React, you can use an online code playground. Try a Hello World template on [CodePen](codepen://hello-world) or [CodeSandbox](https://codesandbox.io/s).

		## HTML Template


		- Try the [Tutorial](/tutorial/tutorial.html) for a hands-on practical example.

		### Install React

Break out Installation into top-level doc section #452

Break out Installation into top-level doc section #452

Uh oh!

Conversation

alexkrolick commented Dec 20, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reactjs-bot commented Dec 20, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bvaughn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexkrolick Dec 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexkrolick commented Dec 22, 2017

Uh oh!

bvaughn commented Dec 22, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexkrolick commented Dec 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexkrolick Dec 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon commented Dec 22, 2017

Uh oh!

alexkrolick commented Dec 23, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gaearon commented Dec 23, 2017

Uh oh!

alexkrolick commented Dec 20, 2017 •

edited

Loading

reactjs-bot commented Dec 20, 2017 •

edited

Loading

alexkrolick Dec 22, 2017 •

edited

Loading

alexkrolick commented Dec 22, 2017 •

edited

Loading

alexkrolick Dec 22, 2017 •

edited

Loading