Docs clarification

[James Hegedus]

I just came across this thread https://twitter.com/piq9117/status/909492740768940032 and thought I would mention that the explanation for what babel-preset-env does, in the CLI warning, is much clearer than the docs here in the repo. As a Babel newbie my first few readings of the repo didn't lead to a full understanding of what the compiled output would be.

A Babel preset that gives you everything standardized in ES2015+

that part, and

Without any configuration options, babel-preset-env behaves exactly the same as babel-preset-latest (or babel-preset-es2015, babel-preset-es2016, and babel-preset-es2017 together).

are not as clear an explanation as the CLI output of:

preset-env without options will compile ES2015+ down to ES5 just like using all the presets together and thus more future proof

The first is confusing as "gives you everything standardized in ES2015+" doesn't tell me the resultant output. And the second half of the second part isn't clear unless you have prior knowledge of what Bable presets are.

The key piece of information that made everything click for me was

preset-env without options will compile ES2015**+** down to ES5

I feel like this should be somewhere at the top of the docs/readme as it explains most clearly what the output is and why you would use it. Then the following documentation makes a lot more sense.

The reason I say all this is that a lot of people are now learning about babel and are told to use preset-env straight off the bat, without explanation. Therefore many will be reading these docs without prior knowledge of presets, how they compose together to target particular levels of the ES spec and potentially without ever having used Babel before.

I hope this nitpick finds you well, this tool is amazing! The use of compat-table and browserlist to make all our lives easier is ingenious. Thanks for your hard work.