New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc feedback] .babelrc doc page starts out very confusingly for newcomers #7196

Open
JonasT opened this Issue Jan 10, 2018 · 4 comments

Comments

Projects
None yet
4 participants
@JonasT

JonasT commented Jan 10, 2018

The .babelrc doc page starts out very confusingly for newcomers:

https://babeljs.io/docs/usage/babelrc

All Babel API options except the callbacks are allowed
(With babel API options not being a link.)

I just got there from the initial setup instructions which says I need one, and then it starts with that confusing sentence about callbacks or options, but not telling me which options there even are.

As I got to this page, my questions were: 1. How does a common .babelrc to start out with look like? (example) and 2. What options can I use there?. None of those are answered, since "Babel API options" is not actually a link or anything and the example right below looks oddly specific, not like a good starting point. (or maybe it is? it doesn't tell me for sure if this is a common example with the transform-react-jsx)

I recommend adding a new section at the top that gives a brief explanation of the purpose of .babelrc, then gives the most basic one most people would want to run, and then actually links the Babel API options and points out the common ones one might want to use.

Right now it seems to be written for people who are already deeply familiar with Babel API options, and not anyone like me who is new to the tool.

@babel-bot

This comment has been minimized.

Show comment
Hide comment
@babel-bot

babel-bot Jan 10, 2018

Collaborator

Hey @JonasT! 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.

Collaborator

babel-bot commented Jan 10, 2018

Hey @JonasT! 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.

@nicolo-ribaudo

This comment has been minimized.

Show comment
Hide comment
@nicolo-ribaudo

nicolo-ribaudo Jan 10, 2018

Member

Isn't the babelrc shown in the homepage (in the "Ready to get started?" section) enough?


OLD ANSWER

How does a common .babelrc to start out with look like? (example)

Maybe we should use an example like

{
  "presets": ["@babel/env"]
}
Member

nicolo-ribaudo commented Jan 10, 2018

Isn't the babelrc shown in the homepage (in the "Ready to get started?" section) enough?


OLD ANSWER

How does a common .babelrc to start out with look like? (example)

Maybe we should use an example like

{
  "presets": ["@babel/env"]
}
@JonasT

This comment has been minimized.

Show comment
Hide comment
@JonasT

JonasT Jan 11, 2018

Maybe, but this example should also be at the top of the page I just linked. People arrive from different links, and I didn't get to the section on the homepage you describe I think but instead to the link I gave above.

JonasT commented Jan 11, 2018

Maybe, but this example should also be at the top of the page I just linked. People arrive from different links, and I didn't get to the section on the homepage you describe I think but instead to the link I gave above.

@simonbuchan

This comment has been minimized.

Show comment
Hide comment
@simonbuchan

simonbuchan Jan 22, 2018

options is a link, and I remember it always being so? That said, it links the the API page, and you have to scroll down to find the actual options.

It always seemed weird to me that the docs for the transform options were not in the page describing the way they will be set 99% of time. I don't think babel needs to go full https://webpack.js.org/configuration/ but maybe moving options to babelrc could make sense, especially now .babelrc.js exists, and lets you define the callback and regex options. That said, that makes the API page pretty anemic, so just merging the two maybe?

In any case babel 7 will require rewriting pretty much the whole thing anyway (e.g. #5276 and babel --env-name obsoletes the whole env section)

simonbuchan commented Jan 22, 2018

options is a link, and I remember it always being so? That said, it links the the API page, and you have to scroll down to find the actual options.

It always seemed weird to me that the docs for the transform options were not in the page describing the way they will be set 99% of time. I don't think babel needs to go full https://webpack.js.org/configuration/ but maybe moving options to babelrc could make sense, especially now .babelrc.js exists, and lets you define the callback and regex options. That said, that makes the API page pretty anemic, so just merging the two maybe?

In any case babel 7 will require rewriting pretty much the whole thing anyway (e.g. #5276 and babel --env-name obsoletes the whole env section)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment