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

Improve Docs #9428

Open
TheJaredWilcurt opened this Issue Jan 29, 2019 · 2 comments

Comments

Projects
None yet
3 participants
@TheJaredWilcurt
Copy link

TheJaredWilcurt commented Jan 29, 2019

This page has an "Options" section, but does not show you WHERE to put the options

After several minutes of looking (shouldn't have taken that long, there should have just been a link or code example on the page) in your docs I finally found this:

{
  "plugins": [
    [
      "transform-async-to-module-method",
      {
        "module": "bluebird",
        "method": "coroutine"
      }
    ]
  ]
}

WHICH DOES NOT HELP, because transform-async-to-module-method is not the name of any plugin listed on that page. And specifically the thing that I want to use @babel/plugin-proposal-optional-chaining is not called @babel/plugin-proposal-optional-chaining on the page, it is called optional-chaining. So I already know that I can't trust your documentation. I don't know if the above example is even related to what I am looking for, because the the page I care about just calls it "Options". Which is vague and impossible to search for. It's not "Plugin Options" or "Plugin Settings" or "Transform Plugin Options" or anything to denote that these settings are specifically for this thing. Making me not even sure if the above example is even related, especially since transform-async-to-module-method has nothing to do with what I'm looking for and seemingly doesn't actually exist. Even if the example is the correct syntax I don't know if it wants transform-async-to-module-method to be replaced with optional-chaining or plugin-proposal-optional-chaining or @babel/plugin-proposal-optional-chaining. But again, that's assuming it's even related at all, which there are no good indications of.

Eventually, after an hour of trying to find ANY examples, (blog posts, medium articles, stack overflow, etc) of how to use options in Babel and ONLY occasionally finding someone linking to the same bad example shown above, I gave up. I literally went to GitHub and searched across every open source JavaScript file on the site for anyone using @babel/plugin-proposal-optional-chaining and EVENTUALLY found the example below.

  plugins: [
    [ '@babel/plugin-proposal-optional-chaining', { loose: true } ],
  ]

Why can't you just put that on the same page, right where the options are. Why can't every page just have an example of how to use the options. Where they actually go. Or at least link to an example that makes sense and links to the plugin page for what is used in the example, since the names actually listed on the plugin example are not the actual names of the plugins.... which is just a whole other issue.

Fix your docs. They are infuriating.

@babel-bot

This comment has been minimized.

Copy link
Collaborator

babel-bot commented Jan 29, 2019

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

@existentialism

This comment has been minimized.

Copy link
Member

existentialism commented Jan 30, 2019

Sorry for the frustration.

I agree that adding a link from each plugin's options section that points to https://babeljs.io/docs/en/plugins#plugin-options would be helpful.

Would you be up for a PR?

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