The section in the docs on Polyfills is unclear
- Dominant language
- TypeScript
- Stars
- 777
- Forks
- 1.4k
- Avg merge
- 16h 45m
- Merged PRs (30d)
- 3
Description
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](https://github.com/zloirock/core-js) (to polyfill ECMAScript features) first, in our entry file to emulate a full ES2015+ environment since [@babel/polyfill](https://babeljs.io/docs/babel-polyfill) has been [deprecated](https://babeljs.io/docs/usage#polyfill-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.
Contributor guide
No contributing guide indexed for this repository
Research direction
Open the Polyfills section at https://babeljs.io/docs/usage and compare its deprecation notice, installation instructions, and summary. Clarify whether @babel/polyfill should be used, distinguish it from core-js guidance, and ensure the final section consistently explains the recommended path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 52/100