The section in the docs on Polyfills is unclear

[Richardinho]

IMHO, the section on Polyfills in the documentation - https://babeljs.io/docs/usage - is not very clear.
The section starts off saying:

As of Babel 7.4.0, this package has been deprecated in favor of directly including core-js/stable (to polyfill ECMAScript features):

Firstly, the deprecated package itself is not stated, which is a bit confusing (although I assume it's @babel/polyfill).

Secondly, it's not clear whether or not we're supposed to ignore this section entirely because of the deprecation warning.
The fact that the section later includes instructions on how to install @babel/polyfill makes me think that these are old instructions and so we should ignore them, but I'm not sure because it also includes instructions for using core-js.

After these instructions we have:

Then import core-js (to polyfill ECMAScript features) first, in our entry file to emulate a full ES2015+ environment since @babel/polyfill has been deprecated:

So what is this saying? all we need to do is import core-js and all the previous instructions are irrelevant? Or we need to follow the preceding instructions and install core-js?

Then further down the page, in the summary, it mentions @babel/polyfill again as if it's not deprecated!

It seems to me that this section should be split up into two sections:

1. How to use @babel/polyfill if you really want to, with the caveat that it's deprecated
2. How to use core-js

Or perhaps just say that @babel/polyfill is deprecated and only have the second section.

[babel-bot]

Hey @Richardinho! We really appreciate you taking the time to report an issue. The collaborators
on this project attempt to help as many people as possible, but we're a limited number of volunteers,
so it's possible this won't be addressed swiftly.

If you need any help, or just have general Babel or JavaScript questions, we have a vibrant Slack
community that typically always has someone willing to help. You can sign-up here
for an invite.