rearrange everything to make it work in the TOC

Author: jenweber

guides/advanced-use.md renamed to guides/advanced-use/index.md

@@ -0,0 +1,9 @@
+# Ember CLI API Documentation
+
+The API docs for Ember CLI are mainly for addon authors, advanced Ember app developers, and contributors to the CLI itself.
+
+## [https://ember-cli.com/api/](https://ember-cli.com/api/) 
+
+The docs are the main resource for information like build pipeline modifications, addon author APIs, advanced configurations, and more.
+
+The API documentation is built from the code comments in the main CLI codebase, [ember-cli on GitHub](https://github.com/ember-cli/ember-cli). If you spot an issue in the documentation, please open an issue or pull request on that repository. 

guides/api-documentation/index.md

@@ -1,4 +1,4 @@
-# Basic use
+# CLI Commands
 
 In their day to day work, most Ember developers use only a small number of CLI commands.
 We'll cover them here, along with a quick tutorial of how to use the `--help` option.
@@ -158,6 +158,8 @@ ember build [options]
 
 Although you can upload the built files to a server yourself, many Ember projects use a community addon called [ember-cli-deploy](https://github.com/ember-cli-deploy/ember-cli-deploy) to get their apps into production. `ember-cli-deploy` has a plugin system to make it easy to deploy to many cloud vendors. Search [EmberObserver for "deploy"](https://emberobserver.com/?query=deploy) to browse available options.
 
+Ember apps can be built with only three environments: development, production, and testing.
+
 ### Example
 
 This command builds the app using the production configuration, so that means by default, it will use maximum minification for best app performance.

guides/basic-use.md renamed to guides/basic-use/cli-commands.md

@@ -6,26 +6,28 @@
 * Recent version of [node](https://nodejs.org/en/download/), which comes included in `yarn` or `npm` 
 * Mac users need [Watchman](https://facebook.github.io/watchman/) (not the npm version!)
 
-First, we first need to have a package manager installed. A package manager installs new dependencies from the command line, whether they are used as commands or in the app itself. A package manager is an important tool for modern web app development. Follow these installation instructions for [npm](https://www.npmjs.com/get-npm) or [yarn](https://yarnpkg.com/en/docs/install). While these two tools have somewhat different features, both are compatible with Ember app development.
+First, we first need to have a package manager installed. A package manager installs new dependencies from the command line, whether they are used as commands or in the app itself. Follow these installation instructions for [npm](https://www.npmjs.com/get-npm) or [yarn](https://yarnpkg.com/en/docs/install). While these two tools have somewhat different features, both are compatible with Ember app development.
 
 We'll know installation is successful when `npm --version` or `yarn --version` returns the version number. 
 
 It is recommend to install the most recent LTS (long term support) version of `node`. Restart the console after installing your package manager.
 
-Mac users may need to install [Watchman](https://facebook.github.io/watchman/) via [Homebrew](http://brew.sh/). Watchman helps correct for some buggy file watching behavior in MacOS. Do not use the `npm` package by the same name.
+## Installing the ember-cli
 
 ```
-brew install watchman
+npm install -g ember-cli
 ```
 
-## Installing
+This will make the `ember` command available throughout your project folders. The installation is successful if `ember -v` returns a version number. When it is run inside of an Ember app directory, it will show the version of the app, otherwise it will show the globally installed version of the CLI.
+
+### Additional steps for Mac users
+
+Mac users may need to install [Watchman](https://facebook.github.io/watchman/) via [Homebrew](http://brew.sh/). Watchman helps correct for some buggy file watching behavior in MacOS. Do not use the `npm` package by the same name.
 
 ```
-npm install -g ember-cli
+brew install watchman
 ```
 
-This will make the `ember` command available throughout your project folders. The installation is successful if `ember -v` returns a version number. When it is run inside of an Ember app directory, it will show the version of the app, otherwise it will show the globally installed version of the CLI.
-
 ## Versioning
 
 The Ember CLI is backwards compatible, meaning that the latest CLI can be used on older app versions. New versions of the CLI are released roughly every 6 weeks, in step with versions of Ember.js itself.

guides/installing-and-upgrading.md renamed to guides/basic-use/index.md

@@ -0,0 +1,43 @@
+# Using addons
+
+Check out [Ember Observer](https://www.emberobserver.com/) to see what kinds of npm libraries are ready-made for your app!
+
+The modern web developer has an incredible selection of open source code that they can use through the npm ecosystem, plus great tools for writing their own modules. Ember developers are free to use regular npm packages in their apps, but there are also thousands of packages that are made specifically for the Ember ecosystem. We call such packages "addons."
+
+Addons are often JavaScript code, reusable UI components, compiling tools, deployment pipelines, templates, stylesheets, and more. Think of addons as node.js libraries with superpowers. In addition to the usual functionality of an npm package, addons can also help with generating new files, preprocessing, file fingerprinting, and more.
+
+## Finding and using community addons
+
+[Ember Observer](https://www.emberobserver.com/) is the definitive way to explore community addons. Although addons can be found by [searching the npm repository directly](https://www.npmjs.com/search?q=ember), Ember Observer has ranked lists of the most popular addons and ratings to help developers choose between them. Most are made to drop right into your app with zero configuration. Many addons are backwards-compatible to earlier versions of Ember too!
+
+To install an addon, use:
+
+```bash
+ember install <addon-name>
+```
+
+To be safe, it's a good idea to restart the local server after installing new dependencies, and especially before trying to debug an addon that isn't working. Also, be sure to check out the project's README to see if there are any additional installation steps to take.
+
+The `ember install` command is similar to the `npm install` you might already be familiar with. It creates an entry in the app's `package.json` and downloads the addon and its dependencies into a `node_modules` directory. However, `ember install` does even more than `npm`. Some addons create new files or make modifications to your app when they are installed via `ember install`.
+
+### Choosing an addon
+
+The [top 100 list](https://www.emberobserver.com/lists/top-addons) is an important first stop for new developers. Many Ember users have a personal set list of addons that they include in all their apps, and this is the best way to find out what those addons might be. Some addons are totally unique to Ember, while others exist to make it easier to use features of regular npm packages within an app.
+
+For example, these community-authored addons bring in familiar functionality from regular npm packages:
+
+- Stylesheet tooling like [ember-cli-sass](https://www.emberobserver.com/addons/ember-cli-sass), which provides [Sass](https://sass-lang.com/) as an alternative to plain CSS
+- JavaScript utilities like [ember-moment](https://www.emberobserver.com/addons/ember-moment), which offers some Ember conveniences to the base [moment library](https://www.npmjs.com/package/moment)
+- Full UI frameworks and design kits like [ember-bootstrap](https://www.emberobserver.com/addons/ember-bootstrap), [semantic-ui-ember](https://www.emberobserver.com/addons/semantic-ui-ember), and [ember-paper](https://www.emberobserver.com/addons/ember-paper). These offer easier, more reliable, more performant functionality than just using the npm packages directly.
+
+Here are just a few examples of popular community-maintained addons unique to Ember, in no particular order:
+
+- A wealth of UI component libraries, like [ember-power-select]() and [ember-basic-dropdown](https://www.emberobserver.com/addons/ember-basic-dropdown)
+- Tools to automate deployment, like [ember-cli-deploy](https://www.emberobserver.com/categories/deployment) and its own ecosystem of plugins
+- Testing tools like [ember-test-selectors](https://www.emberobserver.com/addons/ember-test-selectors), to make DOM assertions in testing easier and clearer, and [ember-a11y-testing](https://www.emberobserver.com/addons/ember-a11y-testing) to check for accessibility
+- Authentication libraries and plugins, like [torii](https://www.emberobserver.com/addons/torii) and [ember-simple-auth](https://www.emberobserver.com/addons/ember-simple-auth), and [ember-oauth2](https://www.emberobserver.com/addons/ember-oauth2)
+- Async and state management tools like [ember-concurrency](https://www.emberobserver.com/addons/ember-concurrency) and [ember-lifeline](https://www.emberobserver.com/addons/ember-lifeline). Don't let a user's impatient clicks kick off 100 API requests.
+- [liquid-fire](https://www.emberobserver.com/addons/liquid-fire), for animating things like route transitions to provide a smooth, native-app-like experience.
+- and so many more!
+
+Open Source projects like these addons rely on community members helping out. Some addons are sponsored by companies, but many are maintained on 100% volunteer time. If something doesn't work the way you expect, could be better documented, has a bug, or could be added as a new feature, please speak up and pitch in!

guides/basic-use/using-addons.md

@@ -0,0 +1,4 @@
+# Using npm packages
+
+<!--Help Wanted--> 
+<!--should cover ember-auto-import, importing from node modules, etc--> 

guides/basic-use/using-npm-packages.md

@@ -0,0 +1,49 @@
+# The Ember CLI
+
+The Ember CLI (command line interface) is the official way to create, build, test, and serve the files that make up an Ember.js app or addon.
+Many things have to happen before for any web app is ready for the browser, and the Ember CLI helps you get there with zero configuration. 
+
+```bash
+npm install -g ember-cli
+```
+
+Visit the [ember-cli](https://github.com/ember-cli/ember-cli) on GitHub for information on the latest releases and new features.
+
+## Learning the CLI
+
+Although these CLI guides have a lot of content, a typical Ember developer will only need to know and use a small fraction of the information. 
+For new users, the recommended learning path is to first do the Ember.js [Quickstart](https://guides.emberjs.com/release/getting-started/quick-start/) and [Tutorial](https://guides.emberjs.com/release/tutorial/ember-cli/), which teach the commands one by one while building a sample app. Then, they should review the Basic Use section of this site as a reference resource.
+
+True to form, the CLI comes with a command-line-based help system too. At any point, if you're curious what a command does and what the options are, you can add `--help` and press enter to find out more.
+
+## What are addons?
+
+There are thousands of JavaScript libraries that work great in Ember. When an npm package offers some Ember-specific conveniences, we call it an “addon.” Ember CLI’s addon system provides a way to create reusable units of code, share components and styling, extend the build tooling, and more — all with minimal configuration. 
+
+To view a complete list of addons, visit [EmberObserver](https://emberobserver.com). 
+
+You can still use your favorite npm packages directly too. If they are not available as addons yet, you can add most of them using [ember-auto-import](https://github.com/ef4/ember-auto-import), adding them to the build pipleine yourself, or by creating wrappers.
+
+## Why do we need a CLI?
+
+The Ember CLI is like a dependency packager, test runner, optimizer, and local server all rolled into one. Since all the features were built to work together, tasks like upgrading the app version or deploying can be automated with production-ready, open source plugins. The CLI is backwards compatible with older apps, and maintains a six-week release schedule.
+
+The CLI's job is to make your work easier.
+It was built with the philosophy that a developer should be able to focus on building great apps, not reengineering how to fit all the pieces together at each stage of an app's lifecycle (creation, local development, production deployments). The result is apps that are more maintainable and approachable, since there are established architectural patterns across individuals, teams, and companies.
+
+However, if you want to make your own adjustments like use a different testing library, you still can.
+
+## Getting help
+
+Do you have questions? Run into an issue or a bug? Get support from the community. A list of chat rooms, forums, and more is available [here](https://www.emberjs.com/community/).
+
+## Contributing
+
+The Ember CLI is developed and maintained by a group of open source volunteers from many different companies and backgrounds. If you have an idea for a feature, a bug to report, or just want to help out where it is needed, you can reach the team via [GitHub](https://github.com/ember-cli), the [Ember Community forums and chat](https://www.emberjs.com/learn/), or drop by the weekly meeting that is open to the public.
+
+### Places to contribute
+
+- [The main ember-cli codebase](https://github.com/ember-cli/ember-cli) 
+- [This documentation site](https://github.com/ember-learn/cli-guides)
+- Official projects under the [ember-cli organization](https://github.com/ember-cli/) 
+- Search the community's CLI plugins on [EmberObserver](https://emberobserver.com)

guides/index.md

@@ -2,97 +2,33 @@
   url: 'index'
   skip_toc: true
   pages:
-    - title: "Ember-Cli Guides"
+    - title: "The Ember CLI"
       url: ""
 
-- title: 'Overview'
-  url: 'overview'
+- title: 'Basic Use'
+  url: 'basic-use'
   pages:
-    - title: 'What is the CLI'
+    - title: 'Installing and upgrading'
       url: 'index'
-    - title: 'Docs layout'
-      url: 'layout'
-    - title: 'Why it should be used'
-      url: 'why'
-    - title: 'How to contribute'
-      url: 'contribute'
+    - title: 'CLI commands'
+      url: 'cli-commands'
+    - title: 'Using addons'
+      url: 'using-addons'
+    - title: 'Using npm packages'
+      url: 'using-npm-packages'
 
-- title: 'Quickstart Tutorial'
-  url: 'tutorial'
+- title: 'Writing addons'
+  url: 'writing-addons'
   pages:
-  - title: 'ember new'
-    url: 'new'
-  - title: 'ember server'
-    url: 'server'
-  - title: 'ember test'
-    url: 'test'
-  - title: 'ember generate'
-    url: 'generate'
-  - title: 'ember install'
-    url: 'install'
-
-- title: 'Basic use'
-  url: 'usage'
-  pages:
-  - title: 'using the "help" commmand'
+  - title: 'Addon structure'
     url: 'index'
-  - title: 'ember new'
-    url: 'new'
-  - title: 'ember server'
-    url: 'server'
-  - title: 'ember test'
-    url: 'test'
-  - title: 'ember generate'
-    url: 'generate'
-  - title: 'ember install'
-    url: 'install'
-  - title: 'feature flags & configurations'
-    url: 'feature-flags'
-  - title: 'Environmental variables'
-    url: 'environmental-variables'
-  - title: 'File tree reference'
-    url: 'file-tree'
-  - title: 'addons/dependencies'
-    url: 'addons'
-  - title: 'Upgrading'
-    url: 'upgrading'
+  - title: 'Tutorial: addon components'
+    url: 'tutorial-addon-components'
+  - title: 'Testing'
+    url: 'testing'
 
 - title: 'Advanced use'
-  url: 'advanced'
+  url: 'advanced-use'
   pages:
-  - title: 'shims'
+  - title: 'Advanced'
     url: 'index'
-  - title: 'broccoli'
-    url: 'broccoli'
-  - title: 'custom blueprints'
-    url: 'blueprints'
-  - title: 'CSS compilation'
-    url: 'css'
-  - title: 'Using another testing library'
-    url: 'alternative-testing-library'
-  - title: 'more on dependencies'
-    url: 'dependencies'
-  - title: 'more configurations'
-    url: 'configurations'
-
-- title: 'Addon authoring'
-  url: 'addons'
-  pages:
-  - title: 'Overview'
-    url: 'index'
-  - title: 'What is an addon'
-    url: 'what-is-an-addon'
-  - title: 'Learning to build addons'
-    url: 'building-addons'
-  - title: 'Creating a standalone addon'
-    url: 'creating'
-  - title: 'Creating an in-repo addon'
-    url: 'in-repo'
-  - title: 'Making an npm package wrapper'
-    url: 'npm'
-  - title: 'Using the dummy app'
-    url: 'dummy'
-  - title: 'Including assets'
-    url: 'assets'
-  - title: 'Testing your addon'
-    url: 'testing'