babel / babel/website

New Docs pages

Open
#1,628 6 comments 0 reactions 0 assignees View on GitHub
babel 7 docs new site
Dominant language
TypeScript
Stars
777
Forks
1.4k
Avg merge
16h 45m
Merged PRs (30d)
3

Description

> TL;DR What new docs do we need?

In addition to the docs for v7 release, we should revamp a lot of missing information. Creating this issue to track some high level and specific topics to add and people can take them as we go.

- [x] "About/Basics" page: https://github.com/babel/website/issues/1391, https://github.com/babel/website/issues/1327 for those new to JavaScript/Babel/npm/etc.
- Related: glossary page? https://github.com/babel/website/issues/1120
- [x] Config (currently https://github.com/babel/website/blob/master/docs/babelrc.md), PR https://github.com/babel/babel/pull/7358
- lookup behavior
- merging behavior
- file names (`.babelrc` vs. `package.json`, etc) and why you would use which, and examples
- use cases: how it is used with compiling `node_modules`, symlinking, monorepo, node, webpack
- commonly used options: `env` and `overrides`
- `only/ignore` (https://github.com/babel/website/issues/703)
- [ ] document babelrc and babelrcRoots https://github.com/babel/babel/pull/7911
- [ ] Page on Caching: https://github.com/babel/babel/pull/6350
- `sourceType`
- Babel v6 assumed all files as `module` so explain the options and reasoning, etc.
- [ ] Page to explain supported environments (Node 4, etc) for the tool **itself** and for the output code (ES5, Internet Explorer with specific plugins)

## Later

- API docs
- Move [`babel-handbook`](https://github.com/jamiebuilds/babel-handbook) to the repo, also helps with translation since that already uses crowdin.
- Previous issues to reference: https://github.com/babel/website/issues/1160, https://github.com/babel/website/issues/334
- Revamp contributing page (it's own effort)
- Translations with crowdin https://github.com/babel/website/issues/1619 (we have the oss tier) but I don't think we should start until we get docs redone anyway so we don't waste people's time.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the remaining unchecked topics and the linked Babel website issues and pull requests, especially the existing docs/babelrc.md page and the babelrc/babelrcRoots work. Define one specific documentation topic before proceeding; the broader issue is done only when its selected missing page or section is written and linked from the documentation site.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js, webpack
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
15/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.