Add a “What’s Going On Here?” section to User Guide

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

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

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