Create-react-app: Add a “What’s Going On Here?” section to User Guide

[gaearon]

Got this idea from conversation with @nitishdayal on Twitter.

There are some people who don’t feel comfortable with a tool until they know how it maps to a lower level abstraction. That is, until they know what’s happening end to end.

I think this is something lacking in our docs right now. We don’t really explain what we’re abstracting away, and what the overall flow is. I remember doing something similar for Redux at some point, and it really helped people (they stopped asking the same questions).

I want to have a new doc section that explains what exactly happens when you run npm start, and what happens when you run npm run build. It should be approachable to somebody who knows how browsers work, but aren’t familiar with the JS ecosystem or single-page apps.

Not as much in terms of technologies ("WebpackDevServer starts"), but more in terms of the actual flow (e.g. "A bundler concatenates all modules used by the app in a single JavaScript file. It starts a development web server that serves an HTML page and that JavaScript file. That HTML page automatically includes a script tag pointing to the JavaScript file. When the page loads, that file executes, rendering the React application. A React application is composed of components. [...]")

Anybody wants to help? (Some experience explaining complex things in simple terms is preferred because this will not be a very easy task.)

[nitishdayal]

I'd be happy to help, actually. This file is a good example to illustrate my writing style (repo consists of some written docs I wrote for Wes Bos' JavaScript30 course). While I might not have all the technical knowledge to do _all_ of it, I can probably take a crack at explaining some of the NPM scripts, explaining the dependencies, what the build output looks like and what it means...whatever seems reasonable.

Of course, this is assuming my writing is deemed worthy. :)

EDIT: Updated link to a specific file rather than the whole repo. Less work for you to do. :)

[gaearon]

@nitishdayal Sounds great!

[pedrottimark]

@nitishdayal Am happy to assist you with general review of your draft content according to criteria: 1. correct, 2. clear, 3. complete (for the primary audience).

[mattwelke]

Just wanted to comment and say that while this sounds good, the developers of this tool should really be commended for what they've done so far. I'm new to JS, new to React, basically new to all of this, and create-react-app has helped me immensely. Ironically, it doing so much for me hasn't made me take it for granted, it's given me a chance to see what happens under the hood and understand industry best practices. The documentation is great so far, and continuing to improve it like this suggestion is going to help newcomers even more.

[nitishdayal]

@pedrottimark Got a start on it today, the raw README.md file has comments under the 'yarn build' and 'yarn eject' sections providing some detail about what information I plan on putting there. Any input/feedback is appreciated. Link

[gaearon]

I think this is a good start. Do you want to work on this as a separate document, or distill it into something smaller that we could put right in the User Guide?

[nitishdayal]

Very sorry, completely spaced on this. Life is intense. Started reworking it tonight (5/14 PST), will have completed draft by EOD 5/15 PST.

Whether it's added or integrated as a separate document is up to y'all. I'm trying to strike the right balance between being concise and providing the right amount of information to address the initial concerns. If it's integrated in as a section of the existing documentation, I'll modify it to not reference the Tic Tac Toe example in my repo.

[nitishdayal]

Draft is complete, can be seen here:

CRA: A Closer Look

EDIT: Minor update to yarn start/npm run start to provide more detail about how Babel is used.

[gaearon]

Nice, sorry it took so long. I added a link via https://github.com/facebookincubator/create-react-app/commit/43e794ddbbd43bb5a966d1621e8203282f76a127.