New Docs pages

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.

• “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
• 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 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.

[dczombera]

I think #334 is particular important for people who want to get started writing plugins and/or want to contribute to the project. Even though I have only touched the tip of the iceberg when it comes to understanding the project in order to be able to contribute more serious stuff, I found it very tough to even get started because of the lack of documentation for the API. I think people who consider helping out or want to write plugins are easily scared away and stop all of their efforts because they are frustrated.

I really would like to help you out here because I think it is important and it would also help me to improve my understanding. The question I’m asking myself right now where to start here? 😄 🤔

[sw-yx]

i would love to work on that once the handbook is merged in. anyone i can work with on this?