babel / babel/babel

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

Open
#7,196 4 comments 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
44k
Forks
6k
Avg merge
5d 15h
Merged PRs (30d)
23

Description

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.

Contributor guide

Open the contributing guide

Research direction

Start with the .babelrc page at https://babeljs.io/docs/usage/babelrc and compare it with the initial setup instructions that lead readers there. Add a brief purpose explanation, a basic starting example, and a link to the Babel API options, making clear what the example and common options mean.

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
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.