diff --git a/guides/legacy/asset-compilation.md b/guides/advanced-use/asset-compilation.md
similarity index 79%
rename from guides/legacy/asset-compilation.md
rename to guides/advanced-use/asset-compilation.md
index f312e5d..cc25166 100644
--- a/guides/legacy/asset-compilation.md
+++ b/guides/advanced-use/asset-compilation.md
@@ -1,11 +1,14 @@
-<!-- Unedited copy of asset-compilation -->
+<!-- Cover very very basic Broccoli info. Link to Oli's tutorials. See the Ember Times Readers questions for a great writeup of what broccoli is -->
 
-### Raw Assets
+When working on an Ember app, sometimes you may want to customize how certain kinds of assets are handled. This is referred to as "asset compilation."
 
-* `public/assets` vs `app/styles`
+For information on stylesheets, please see the dedicated section, [Stylesheet compilation](../stylesheets/)
 
-To add images, fonts, or other assets, place them in the `public/assets` directory. For
-example, if you place `logo.png` in `public/assets/images`, you can reference it in
+## Raw Assets
+
+To include images, fonts, or other assets, place them in the `public/assets` directory.
+
+For example, if you place `logo.png` in `public/assets/images`, you can reference it in
 templates with `assets/images/logo.png` or in stylesheets with
 `url('/assets/images/logo.png')`.
 
@@ -13,7 +16,7 @@ This functionality of Ember CLI comes from
 [broccoli-asset-rev](https://github.com/rickharrison/broccoli-asset-rev). Be
 sure to check out all the options and usage notes.
 
-### JS Transpiling
+## JS Transpiling
 
 Ember CLI automatically transpiles future JavaScript (ES6/ES2015, ES2016 and beyond) into standard ES5
 JavaScript that runs on every browser using [Babel JS](https://babeljs.io) with the [Ember CLI Babel](https://github.com/babel/ember-cli-babel) addon.
@@ -23,7 +26,7 @@ need to be transpiled to ES5 by **analyzing your project's browser support targe
 that maps to a [browserlist](https://github.com/ai/browserslist) support rule. These are defined in your
 `config/targets.js` file, which [Ember CLI generates](https://github.com/ember-cli/ember-cli/blob/master/blueprints/app/files/config/targets.js) like so:
 
-```js
+```javascript
 /* eslint-env node */
 module.exports = {
   browsers: [
@@ -43,7 +46,7 @@ simply set any of the options found [here](https://github.com/babel/babel-preset
 For example, if you wanted to explicitly exclude generator function transpilation from your
 output, your configuration would look like this:
 
-```js
+```javascript
 // ember-cli-build.js
 
 /* eslint-env node */
@@ -72,18 +75,16 @@ module.exports = function(defaults) {
 
 As of Version 2.13, Ember CLI uses Babel 6.X for transpilation. Ember CLI versions prior to 2.13 use Babel Babel 5.X, and you can check its documentation for a comprehensive list of [all available transformations](https://github.com/babel/babel.github.io/blob/5.0.0/docs/usage/transformers/index.md) and [options](https://github.com/babel/babel.github.io/blob/5.0.0/docs/usage/options.md).
 
-
-
-### Source Maps
+## Source Maps
 
 Ember CLI supports producing source maps for your concatenated and minified JS source files.
 
 Source maps are configured by the EmberApp `sourcemaps` option, and
-are disabled in production by default. Pass `sourcemaps: {enabled: true}` to your EmberApp constructor to enable source maps for javascript. Use the `extensions` option to add other formats, such as coffeescript and CSS: `{extensions: ['js', 'css', 'coffee']}`. JS is supported out-of-the-box. CSS is not currently supported. For other source formats (Sass, Coffee, etc) refer to their addons.
+are disabled in production by default. Pass `sourcemaps: {enabled: true}` to your EmberApp constructor to enable source maps for JavaScript. Use the `extensions` option to add other formats, such as CSS: `{extensions: ['js', 'css']}`. JS is supported out-of-the-box. CSS is not currently supported. For other source formats, refer to their addons.
 
-Default ember-cli-build.js:
+Default `ember-cli-build.js`:
 
-```js
+```javascript
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
 module.exports = function(defaults) {
@@ -99,52 +100,68 @@ module.exports = function(defaults) {
 };
 ```
 
+## Minifying
 
-### CoffeeScript
+Compiled css-files are minified by `broccoli-clean-css` or `broccoli-csso`,
+if it is installed locally. You can pass minifer-specific options to them using
+the `minifyCSS:options` object in your ember-cli-build. Minification is enabled by
+default in the production-env and can be disabled using the `minifyCSS:enabled`
+switch.
 
-To enable [CoffeeScript](http://coffeescript.org/), you must
-first add [ember-cli-coffeescript](https://github.com/kimroen/ember-cli-coffeescript) to your
-NPM modules:
+Similarly, the js-files are minified with `broccoli-uglify-js` in the
+production-env by default. You can pass custom options to the minifier via the
+`minifyJS:options` object in your ember-cli-build. To enable or disable JS minification
+you may supply a boolean value for `minifyJS:enabled`.
 
-```bash
-ember install ember-cli-coffeescript
-```
+For example, to disable minifying of CSS and JS, add in `ember-cli-build.js`:
 
-The modified `package.json` should be checked into source control. CoffeeScript
-can be used in your app's source and in tests, just use the `.coffee` extension
-on any file. We recommend using version >= 1.16.0 of ember-cli-coffeescript to avoid the need
-to escape `import` and `export` statements.
+```js
+// ember-cli-build.js
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
-Note that earlier versions of the transpiler had explicit support for
-CoffeeScript, but that support has been removed.
+module.exports = function(defaults) {
+  let app = new EmberApp(defaults, {
+    minifyJS: {
+      enabled: false
+    },
+    minifyCSS: {
+      enabled: false
+    }
+  });
 
-### EmberScript
+  //...
+  return app.toTree();
+};
+```
 
-To enable [EmberScript](http://emberscript.com), you must
-first add [broccoli-ember-script](https://github.com/aradabaugh/broccoli-ember-script) to your
-NPM modules:
+### Exclude from minification
 
-```bash
-npm install broccoli-ember-script --save-dev
-```
+Some files should be excluded from minification, such as copied-and-pasted third party scripts that are already minified.
 
-Note that the ES6 module transpiler is not directly supported with Emberscript,
-to allow use of ES6 modules use the `` ` `` character to escape raw Javascript
-similar to the CoffeeScript example above.
+To exclude assets from `dist/assets` from being minified, one can pass options for
+[broccoli-uglify-sourcemap](https://github.com/ef4/broccoli-uglify-sourcemap) like so:
 
-### Emblem
+```js
+// ember-cli-build.js
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
-For [Emblem](http://emblemjs.com/), run the following commands:
+module.exports = function(defaults) {
+  let app = new EmberApp(defaults, {
+    minifyJS: {
+      options: {
+        exclude: ["**/vendor.js"]
+      }
+    }
+  });
 
-```bash
-ember install ember-cli-emblem
+  //...
+  return app.toTree();
+};
 ```
 
-If you're using the older broccoli-emblem-compiler addon, you need to switch to
-ember-cli-emblem. The older broccoli-emblem-compiler compiles directly to JS
-instead of Handlebars and therefore is broken on all newer version of HTMLBars.
+This would exclude the resulting `vendor.js` file from being minified.
 
-### Fingerprinting and CDN URLs
+## Fingerprinting and CDN URLs
 
 Fingerprinting is done using the addon
 [broccoli-asset-rev](https://github.com/rickharrison/broccoli-asset-rev)
@@ -176,7 +193,7 @@ of the md5. Pass `null` to suppress the hash, which can be useful when using `pr
 As an example, this `ember-cli-build` will exclude any file in the fonts/169929
 directory as well as add a cloudfront domain to each fingerprinted asset.
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -209,7 +226,7 @@ background: url('https://subdomain.cloudfront.net/images/foo-735d6c098496507e26b
 
 You can disable fingerprinting in your `ember-cli-build.js`:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -228,14 +245,14 @@ module.exports = function(defaults) {
 Or remove the entry from your `EmberApp` and  `broccoli-asset-rev`
 from your `package.json`.
 
-### Application Configuration
+## Application Configuration
 
 Application configurations from your `ember-cli-build.js` file will be stored inside a
 special meta tag in `dist/index.html`.
 
 sample meta tag:
 
-```js
+```javascript
 <meta name="user/config/environment" content="%7B%22modulePre.your.config">
 ```
 
@@ -243,7 +260,7 @@ This meta tag is required for your ember application to function properly.
 If you prefer to have this tag be part of your compiled javascript files
 instead, you may use the `storeConfigInMeta` flag in `ember-cli-build.js`.
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -257,7 +274,7 @@ module.exports = function(defaults) {
 };
 ```
 
-#### Configuring output paths
+### Configuring output paths
 
 The compiled files are output to the following paths:
 
@@ -298,7 +315,7 @@ The compiled files are output to the following paths:
 
 To change these paths, specify the `outputPaths` config option in `ember-cli-build.js`. The default setting is shown here:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -328,7 +345,7 @@ You may edit any of these output paths, but make sure to update the paths specif
 `app.outputPaths.app.html` default it is `index.html`, and `tests/index.html`. If this is not done,
 your app will not be served with correct asset names.
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -354,7 +371,7 @@ different extension.
 When using CSS preprocessing, only the `app/styles/app.scss` (or `.less` etc)
 is compiled. If you need to process multiple files, you must add another key:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -375,13 +392,13 @@ module.exports = function(defaults) {
 };
 ```
 
-#### Integration
+## Integration
 
 When using Ember inside another project, you may want to launch Ember only when
 a specific route is accessed. If you're preloading the Ember javascript before
 you access the route, you have to disable `autoRun`:
 
-```js
+```javascript
 // ember-cli-build.js
 const EmberApp = require('ember-cli/lib/broccoli/ember-app');
 
@@ -398,7 +415,7 @@ module.exports = function(defaults) {
 To manually run Ember:
 `require("app-name/app")["default"].create({/* app settings */});`
 
-#### Subresource integrity
+## Subresource integrity
 
 SRI calculation is done using the addon
 [ember-cli-sri](https://github.com/jonathanKingston/ember-cli-sri)
@@ -409,7 +426,7 @@ your applications. Subresource integrity is a security concept used to check
 JavaScript and stylesheets are loaded with the correct content when using a
 CDN.
 
-#### Why
+### Why
 
 The reason to add this to your application is to protect against poisoned CDNs
 breaking JavaScript or CSS.
@@ -420,6 +437,6 @@ breaking JavaScript or CSS.
   - The latest [GitHub DDoS attack](http://googleonlinesecurity.blogspot.co.uk/2015/04/a-javascript-based-ddos-attack-as-seen.html)
 - Protection against corrupted code on less trusted servers
 
-#### Customize
+### Customize
 
 To customize SRI generation see: [ember-cli-sri](https://github.com/jonathanKingston/ember-cli-sri)
diff --git a/guides/advanced-use/asset-pipeline.md b/guides/advanced-use/asset-pipeline.md
deleted file mode 100644
index 182a322..0000000
--- a/guides/advanced-use/asset-pipeline.md
+++ /dev/null
@@ -1 +0,0 @@
-<!-- Cover very very basic Broccoli info. Link to Oli's tutorials. See the Ember Times Readers questions for a great writeup of what broccoli is -->
diff --git a/guides/advanced-use/configurations.md b/guides/advanced-use/configurations.md
deleted file mode 100644
index 85a7ab2..0000000
--- a/guides/advanced-use/configurations.md
+++ /dev/null
@@ -1,63 +0,0 @@
-<!-- Should cover at least minification and fingerprinting -->
-<!-- Needs intro! -->
-
-### Minifying
-
-Compiled css-files are minified by `broccoli-clean-css` or `broccoli-csso`,
-if it is installed locally. You can pass minifer-specific options to them using
-the `minifyCSS:options` object in your ember-cli-build. Minification is enabled by
-default in the production-env and can be disabled using the `minifyCSS:enabled`
-switch.
-
-Similarly, the js-files are minified with `broccoli-uglify-js` in the
-production-env by default. You can pass custom options to the minifier via the
-`minifyJS:options` object in your ember-cli-build. To enable or disable JS minification
-you may supply a boolean value for `minifyJS:enabled`.
-
-For example, to disable minifying of CSS and JS, add in `ember-cli-build.js`:
-
-```js
-// ember-cli-build.js
-const EmberApp = require('ember-cli/lib/broccoli/ember-app');
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, {
-    minifyJS: {
-      enabled: false
-    },
-    minifyCSS: {
-      enabled: false
-    }
-  });
-
-  //...
-  return app.toTree();
-};
-```
-
-#### Exclude from minification
-
-Some files should be excluded from minification, such as copied-and-pasted third party scripts that are already minified.
-
-To exclude assets from `dist/assets` from being minified, one can pass options for
-[broccoli-uglify-sourcemap](https://github.com/ef4/broccoli-uglify-sourcemap) like so:
-
-```js
-// ember-cli-build.js
-const EmberApp = require('ember-cli/lib/broccoli/ember-app');
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, {
-    minifyJS: {
-      options: {
-        exclude: ["**/vendor.js"]
-      }
-    }
-  });
-
-  //...
-  return app.toTree();
-};
-```
-
-This would exclude the resulting `vendor.js` file from being minified.
\ No newline at end of file
diff --git a/guides/advanced-use/file-layout.md b/guides/advanced-use/file-layout.md
index 7931cad..4a204ed 100644
--- a/guides/advanced-use/file-layout.md
+++ b/guides/advanced-use/file-layout.md
@@ -1 +1,3 @@
 <!-- A place to talk about the resolver (see ember-cli.com), module imports, and eventually, Module Unification when it becomes a thing -->
+
+<!-- This page is not included in the table of contents and therefore not part of the build yet -->
diff --git a/guides/advanced-use/index.md b/guides/advanced-use/index.md
index afc4cbf..6e70206 100644
--- a/guides/advanced-use/index.md
+++ b/guides/advanced-use/index.md
@@ -1,108 +1,50 @@
-This section of the CLI Guides describes how to make custom configurations to the app's build behavior, testing, and more.
-Ember is designed for a zero config experience for most users, but it was also designed to be extensible. Think of it as configuration without confusion.
+This section of the CLI Guides describes the ecosystem of tools that are behind an app's build behavior, testing, and more.
+Ember is designed for a zero config experience for most users, but it was also designed to be extensible.
+The first step to making your own configurations is to become familiar with some of the vocabulary and tools.
+Later sections will cover how to use them to get work done.
 
-## Overall CLI functionality
+## Broccoli
 
-To begin making configurations, first it is important to understand the overall architecture of what the CLI can do.
-Most custom configuration is done in `ember-cli-build.js`, `environment.js`, and Broccoli plugins.
+Ember uses Broccoli for the build process. Broccoli is an independent project that is similar to tools like webpack and parcel. Although many developers never need to configure Broccoli themselves, they have the option to do so. 
 
-### Broccoli
-
-Ember uses Broccoli for the build process. Broccoli is an independent project that is similar to tools like webpack and parcel. Although many developers never need to configure Broccoli themselves, they have the option to do so. For example, if an app has content in the form of Markdown files that need to be turned into HTML during the build, it could be done with Broccoli. This very app you're reading content on right now follows that architecture, and the work was turned into a [Broccoli plugin](https://github.com/stonecircle/broccoli-static-site-json).
+For example, if an app has content in the form of Markdown files that need to be turned into HTML during the build, it could be done with Broccoli. This very app you're reading content on right now follows that architecture, and the work was turned into a [Broccoli plugin](https://github.com/stonecircle/broccoli-static-site-json).
 
 Just like there are Ember community addons, there are a variety of Broccoli plugins too!
 
-### Babel
+## Babel
 
 The CLI uses Babel as part of the build process. Babel is an independent project used in an incredible percentage of websites. It has an important job, as quoted from [their documentation](https://babeljs.io/docs/en):
 
 > Babel is a toolchain that is mainly used to convert ECMAScript 2015+ code into a backwards compatible version of JavaScript in old browsers or environments.
 
-### Minification
+## Minification
 
 The CLI uses uglify to take dozens of JavaScript files and turn them into something compact and optimized.
 
-### Stylesheet compilation
+## Stylesheet compilation
 
 Ember apps use CSS by default. However there is support for other stylesheet systems like LESS and SASS.
 
-<!-- Show that app/styles/app.css is the entry point-->
-
-<!-- Example of importing stylesheets from node_modules -->
-
-<!-- Example of enabling SASS suppot -->
-
-### Testing framework
+## Testing framework
 
 Ember has official support for QUnit and Mocha. However, other libraries may be used.
 
-### Community build tools
+## Community build tools
 
 A number of community build tools allow developers to use things like Typescript in their Ember apps.
 
-## Configuring the environment
-
-One of the most important customization files is `environment.js`. There, different behavior can be defined based on which environment flag is passed to the `build` command.
-
-### Example asset minification configuration
-
-Some apps may have previously-minified files included as assets.
-Those JavaScript files should not be minified twice! To exclude certain files from minification, add the configuration to `environment.js`:
-
-<!-- Need an example -->
-
-### Example addon configuration
-
-Many developers use a tool called [Mirage]() to make a test API server. By default, Mirage is only available in development, however, with a change in the `production` section of `environment.js`, it can be used in deployed apps.
-
-## Including third party JavaScript libraries
-
-The easiest and best way to include npm packages in an Ember app is to use an Ember Addon version of them. That way, the experience is `ember install ember-addon-name` and `ember serve`. A list of Ember addons can be found on [Ember Observer](https://emberobserver.com)
-
-However, sometimes, developers need to work with libraries or assets that aren't available as addons. The options are, either write an addon wrapper or include the files directly in the build. Writing an addon wrapper is a routine choice for many developers, and a step by step guide is available here <!-- LINK -->
-
-This section describes the options for importing specific assets from `node_modules`, including JavaScript files in the `vendor` folder, and writing shims.
-
-### Importing from `node_modules`
+## Using `testem.js`
 
-### Using the `vendor` directory
+[Testem](https://github.com/testem/testem) is an independent project that the CLI uses to run tests. For example, the `testem.json` file contains specification like which browsers to run tests in.
 
-For files to be included in the default app build, they should go in specific places in the file structure. The `vendor` folder is the most likely place for things like minified `JavaScript` files. 
+## Linting
 
-A typical minified, browser-ready JavaScript file will export a global that can be used throughout the Ember app. To include it in the build and make it accessible, it must be imported in `ember-cli-build.js`:
-
-<!-- EXAMPLE CODE -->
-
-### Using the public folder
-
-By default, images in the public folder will be available to use in app templates:
-
-<!-- EXAMPLE CODE -->
-
-## Testing configuration 
-
-### Using `testem.js`
-
-[Testem]() is an independent project that the CLI uses to run tests. For example, the `testem.json` file contains specification like which browsers to run tests in.
-
-### Linting
-
-A linter is a tool that checks to see if certain coding best practices are being followed, as well as checking for invalid syntax. By default, the CLI uses eslint plus some Ember-specific eslint plugins that help check for likely mistakes.
+A linter is a tool that checks to see if certain coding best practices are being followed, as well as checking for invalid syntax. By default, the CLI uses [eslint](https://eslint.org) plus some Ember-specific eslint plugins that help check for likely mistakes.
 
 To customize linting behavior, edit `.eslintrc.js`. An example configuration might be to enforce using semicolons, or change a rule violation to count as an "error" rather than a warning.
 
-### Continuous integration testing
+## Continuous integration testing
 
-Default Ember apps contain a file called `.travis.yml` that specifies the commands to be used with [Travis](), a Continuous Integration testing vendor.
+Default Ember apps contain a file called `.travis.yml` that specifies the commands to be used with [Travis](https://travis-ci.org/), a Continuous Integration testing vendor.
 
 Developers are free to use other CI providers. They are encouraged to reference the default blueprint of `.travis.yml` to get an idea of what kinds of information to include when configuring other vendors.
-
-## App directory structure
-
-<!-- talk about pods -->
-
-## Custom blueprints
-
-<!-- give an example and link to the cli blueprints -->
-
-## Stylesheet compilation
diff --git a/guides/advanced-use/stylesheets.md b/guides/advanced-use/stylesheets.md
index 4ed2ea0..048ccb1 100644
--- a/guides/advanced-use/stylesheets.md
+++ b/guides/advanced-use/stylesheets.md
@@ -3,17 +3,7 @@
 Ember CLI supports plain CSS out of the box. You can add your css styles to
 `app/styles/app.css` and it will be served at `assets/application-name.css`.
 
-For example, to add bootstrap in your project you need to do the following:
-```bash
-bower install bootstrap --save
-```
-
-In `ember-cli-build.js` add the following:
-```js
-app.import('bower_components/bootstrap/dist/css/bootstrap.css');
-```
-it's going to tell [Broccoli](https://github.com/broccolijs/broccoli) that we want
-this file to be concatenated with our `vendor.css` file.
+<!-- Ought to show how to import stylesheets from node_modules, or link to it in the guides if it's there -->
 
 To use a CSS preprocessor, you'll need to install the appropriate
 [Broccoli](https://github.com/broccolijs/broccoli) plugin. When using a
diff --git a/guides/reference/common-issues.md b/guides/appendix/common-issues.md
similarity index 89%
rename from guides/reference/common-issues.md
rename to guides/appendix/common-issues.md
index 98ae9a8..86026a1 100644
--- a/guides/reference/common-issues.md
+++ b/guides/appendix/common-issues.md
@@ -1,11 +1,13 @@
-### Don't install `npm` packages with `sudo`
+Having trouble with something? Check out these common pitfalls.
+
+## Don't install `npm` packages with `sudo`
 
 Installing packages such as `bower` with `sudo` powers can lead to permissions
 issues and ultimately to problems installing dependencies. See
 [https://gist.github.com/isaacs/579814](https://gist.github.com/isaacs/579814)
 for a collection of various solutions.
 
-### Installing From Behind a Proxy
+## Installing From Behind a Proxy
 
 If you're behind a proxy, you might not be able to install because Ember CLI–or
 some of its dependencies–tries to `git clone` a `git://` URL. (In this scenario,
@@ -28,18 +30,18 @@ As a workaround you can configure `git` to make the translation:
 git config --global url."https://".insteadOf git://
 ```
 
-### Using Canary Build instead of release
+## Using Canary Build instead of release
 
 In most cases you should use a stable release, but if you need to install a canary version to test beta features, you'd do it like this:
 
 For Ember: `bower install ember#canary --resolution canary`
 For `ember-data`: `npm install --save-dev emberjs/data#master`
 
-### Windows Build Performance Issues
+## Windows Build Performance Issues
 
-See [The Windows Section](/release/reference/windows/) for more details.
+See [The Windows Section](/release/appendix/windows/) for more details.
 
-### Cygwin on Windows
+## Cygwin on Windows
 
 Node.js on Cygwin is no longer supported [more
 details](https://github.com/nodejs/node/wiki/Installation#building-on-cygwin)
@@ -47,11 +49,11 @@ Rather then using Cygwin, we recommend running Ember CLI natively on windows,
 or via the new [Windows Subsystem
 Linux](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide).
 
-<!-- ### Usage with Docker -->
+<!-- ## Usage with Docker -->
 <!-- Possible topic for future development. -->
 
 
-### Usage with Vagrant
+## Usage with Vagrant
 
 [Vagrant](https://vagrantup.com) is a system for automatically creating and
 setting up development environments that run in a virtual machine (VM).
@@ -59,7 +61,7 @@ setting up development environments that run in a virtual machine (VM).
 Running your Ember CLI development environment from inside of a Vagrant VM will
 require some additional configuration and will carry a few caveats.
 
-#### Ports
+### Ports
 
 In order to access your Ember CLI application from your desktop's web browser,
 you'll have to open some forwarded ports into your VM. Ember CLI by default
@@ -78,7 +80,7 @@ Vagrant.configure("2") do |config|
 end
 ```
 
-#### Watched Files
+### Watched Files
 
 The way Vagrant syncs directories between your desktop and vm may prevent file
 watching from working correctly. This will prevent rebuilds and live reloads
@@ -87,7 +89,7 @@ from working correctly. There are several work arounds:
 1. Watch for changes by polling the file system via: `ember serve --watcher polling`.
 2. Use [nfs for synced folders](https://docs.vagrantup.com/v2/synced-folders/nfs.html).
 
-#### VM Setup
+### VM Setup
 
 When setting up your VM, install Ember CLI dependencies as you normally would.
 Some of these dependencies (such as [broccoli-sass](#sass)) may have native
@@ -97,7 +99,7 @@ depenencies that may require recompilation. To do so run:
 npm rebuild
 ```
 
-#### Provider
+### Provider
 
 The two most common Vagrant providers, VirtualBox and VMware Fusion, will both
 work. However, VMware Fusion is substantially faster and will use less battery
diff --git a/guides/reference/dev-tools.md b/guides/appendix/dev-tools.md
similarity index 100%
rename from guides/reference/dev-tools.md
rename to guides/appendix/dev-tools.md
diff --git a/guides/appendix/faq.md b/guides/appendix/faq.md
new file mode 100644
index 0000000..fb7bfcd
--- /dev/null
+++ b/guides/appendix/faq.md
@@ -0,0 +1,4 @@
+
+<!-- This page is not included in the table of contents and therefore not part of the build yet -->
+
+<!-- Do I need to use the CLI, why broccoli instead of webpack, node version compatibility? -->
diff --git a/guides/appendix/index.md b/guides/appendix/index.md
new file mode 100644
index 0000000..eec17d6
--- /dev/null
+++ b/guides/appendix/index.md
@@ -0,0 +1,5 @@
+Apps come in so many types, shapes, and sizes that it's not possible to cover every edge case or configuration in the main guides.
+
+The Appendix is the home of content that may not be frequently used, but is very helpful to developers who are working with stubborn bugs, unusual constraints, or older apps.
+
+Help add to this section by opening issues for the [Ember CLI Guides](https://github.com/ember-learn/cli-guides).
diff --git a/guides/reference/windows.md b/guides/appendix/windows.md
similarity index 97%
rename from guides/reference/windows.md
rename to guides/appendix/windows.md
index 4245b76..18f3e3e 100644
--- a/guides/reference/windows.md
+++ b/guides/appendix/windows.md
@@ -1,4 +1,4 @@
-Windows Vista and newer Windows versions are fully supported.
+Windows versions as far back as Vista are fully supported when using the Ember CLI.
 
 To get started ensure the following dependencies are installed:
 
diff --git a/guides/basic-use/assets-and-dependencies.md b/guides/basic-use/assets-and-dependencies.md
new file mode 100644
index 0000000..ad2c0d3
--- /dev/null
+++ b/guides/basic-use/assets-and-dependencies.md
@@ -0,0 +1,86 @@
+<!-- Some content redundancy with using addons and using npm packages pages -->
+<!-- A section should clearly show using WASM files, I think -->
+
+Assets and dependencies are the resources your app needs to work.
+In general, when people say "assets", they mean things that the developer has added themselves to the app, like images and fonts, while "dependencies" are resources that come from third party libraries.
+
+## Where should assets and dependencies go?
+
+Here are the most common places:
+
+- Every Ember app has a file called `package.json` that lists node modules used by the app.
+The code itself goes in `node_modules` during `npm install`, just like in many non-Ember JavaScript projects
+- The `vendor` directory, which is a common home for third party JavaScript that is copied and pasted in
+- The `public` directory, the typical place for assets like images
+- The `styles` directory, for stylesheets like CSS, SASS, or LESS
+plus folders like `vendor` and `public` that hold can many other files of the developer's choice
+
+Some older apps may use a package manager and registry called Bower, which has
+a `bower_components` directory. Bower itself is deprecated and should not be used.
+
+<!-- 
+If addons are installed accidentally with `npm install` or `yarn install`,
+the blueprints can be run with .... what?
+-->
+
+## NPM and Yarn
+
+Ember CLI supports both [npm](https://www.npmjs.com) and [Yarn](https://yarnpkg.com/)
+for node modules management.
+
+By default, new apps use `npm`.
+Both tools offer similar functionality, and which one to choose is up to
+the developer's preference.
+Dependencies listed in `package.json` can be installed with with either `npm install` or `yarn install`. The files for those packages are added to the `node_modules` folder of the app.
+
+There are two ways to switch from `npm` to `yarn`.
+Either include an option when the app is created, like `ember new --yarn`,
+or run `yarn install` to generate a `yarn.lock` file.
+Ember will detect the `yarn.lock` file and start using it instead
+for any `ember install some-addon-name` commands.
+Don't forget to delete the `package-lock.json` file if the app
+already has one.
+In cases where both a `yarn.lock` file and a `package-lock.json`
+file are present, Ember CLI will default to using Yarn.
+However, having both files causes confusion for collaborators and
+is incompatible with some CI systems.
+
+To switch from `yarn` to `npm`, delete the `yarn.lock`
+and run `npm install` to generate a `package-lock.json`.
+
+Further documentation about npm and Yarn is available at their official
+documentation pages:
+
+* [npm](https://www.npmjs.com)
+* [Yarn](https://yarnpkg.com)
+
+### The `node_modules` directory
+
+New apps list the `node_modules` directory in the app's `.gitignore` configuration,
+meaning that any changes to the contents of the directory are ignored by git.
+Using the npm configuration files allows collaborators to download your
+app source code and get the `node_modules` installed locally by executing 
+`npm install` themselves.
+
+### Effects of new dependencies on local servers
+
+When an app is being served locally, the Ember CLI will not watch for changes in the `package.json` file. Therefore, 
+if you install npm dependencies via `npm install <dependencies>`, you will 
+need to restart your Ember CLI server session manually.
+
+Dependencies installed with `ember install some-addon-name` will cause a refreash
+of a local server.
+
+### Debugging node_modules dependencies
+
+Errors such as "a module named _____ could not be found" or a colleague's report that "well, the app works on my computer but not yours!" sometimes indicate that
+the local server needs to be restarted or `node_modules` should be reinstalled.
+
+Common resolution steps are to stop the server, and then take one of these steps, and start the server again:
+
+- run `npm install` or `yarn install`
+- Delete the `node_modules` directory and run `npm install` or `yarn install`
+- Delete the `dist` directory (found in apps with versions < 3.4), delete `node_modules`, and `npm install` or `yarn install`
+- If an app uses Bower (a deprecated, npm-like tool), follow all the steps above
+in addition to deleteing `bower_components` and running `bower install`
+
diff --git a/guides/basic-use/configurations.md b/guides/basic-use/configurations.md
index aea0005..babe725 100644
--- a/guides/basic-use/configurations.md
+++ b/guides/basic-use/configurations.md
@@ -1,4 +1,4 @@
-<!-- This page is not yet in production. When it is ready, add it to pages.yml -->
+<!-- This page is not included in the table of contents and therefore not part of the build yet -->
 
 <!-- The bare minimum explanation of what to do with ember-cli-build.js -->
 
diff --git a/guides/basic-use/index.md b/guides/basic-use/index.md
index 86f6d67..afc05ac 100644
--- a/guides/basic-use/index.md
+++ b/guides/basic-use/index.md
@@ -54,7 +54,7 @@ It's safe to ignore this message. However, file-watching won't be as smooth as i
 ### Installing the CLI on Windows
 
 Windows versions as far back as Vista are fully supported, although there are steps you can take to improve your experience.
-You can find more information about this in our section on [Windows support](../reference/windows/)
+You can find more information about this in our section on [Windows support](../appendix/windows/)
 
 ## Getting help
 
diff --git a/guides/basic-use/using-addons.md b/guides/basic-use/using-addons.md
index 089873e..ac4d64d 100644
--- a/guides/basic-use/using-addons.md
+++ b/guides/basic-use/using-addons.md
@@ -29,7 +29,7 @@ The [top 100 list](https://www.emberobserver.com/lists/top-addons) is an importa
 
 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
+- 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 standard 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.
 - TypeScript support through [ember-cli-typescript](https://github.com/typed-ember/ember-cli-typescript)
diff --git a/guides/legacy/dependencies.md b/guides/legacy/dependencies.md
deleted file mode 100644
index ae6bf49..0000000
--- a/guides/legacy/dependencies.md
+++ /dev/null
@@ -1,504 +0,0 @@
-<!-- Some content redundancy with using addons and using npm packages pages -->
-<!-- A section should clearly show using WASM files, I think -->
-
-This section of the guides will show how to add new dependencies to
-an app or addon.
-Examples of dependencies include node modules, standalone JavaScript files,
-images, stylesheets, WebAssembly files, JSON, and more.
-Regardless of the app framework, _somewhere_ there must be logic that
-determines how the files are
-pulled together into a bundle that the browser can understand and use efficiently.
-In Ember, the CLI handles the most common use cases to deliver a zero config experience.
-Here, we'll also cover some of the less common use cases that require some configuration.
-
-## Where should dependencies go?
-
-Here are the most common places:
-
-- Every Ember app has a file called `package.json` that lists node modules used by the app.
-The code itself goes in `node_modules`, just like in many non-Ember JavaScript projects
-- The `vendor` directory, which is a common home for third party JavaScript that is copied and pasted in
-- The `public` directory, the typical place for assets like images
-- The `styles` directory, for stylesheets like CSS, SASS, or LESS
-plus folders like `vendor` and `public` that hold can many other files of the developer's
-choice
-
-Some older apps may use a package manager and registry called Bower, which has
-a `bower_components` directory. Bower itself is deprecated and should not be used.
-
-## Addons as dependencies
-
-Using addons provides the best experience for including new dependencies in an app.
-Visit [EmberObserver](https://emberobserver.com) to browse for addons.
-Installing them with `ember install some-addon-name` ensures that all the files
-go in the right place, and any further setup is completed, like codemods. More details are available in
-[Using Addons](../../basic-use/using-addons/).
-
-<!-- 
-If addons are installed accidentally with `npm install` or `yarn install`,
-the blueprints can be run with .... what?
--->
-
-## NPM and Yarn
-
-Ember CLI supports both [npm](https://www.npmjs.com) and [Yarn](https://yarnpkg.com/)
-for node modules management.
-
-By default, new apps use `npm`.
-Both tools offer similar functionality, and which one to choose is up to
-the developer's preference.
-Dependencies listed in `package.json` can be installed with with either `npm install` or `yarn install`. The files for those packages are added to the `node_modules` folder of the app.
-
-There are two ways to switch from `npm` to `yarn`.
-Either include an option when the app is created, like `ember new --yarn`,
-or run `yarn install` to generate a `yarn.lock` file.
-Ember will detect the `yarn.lock` file and start using it instead
-for any `ember install some-addon-name` commands.
-Don't forget to delete the `package-lock.json` file if the app
-already has one.
-In cases where both a `yarn.lock` file and a `package-lock.json`
-file are present, Ember CLI will default to using Yarn.
-However, having both files causes confusion for collaborators and
-is incompatible with some CI systems.
-
-To switch from `yarn` to `npm`, delete the `yarn.lock`
-and run `npm install` to generate a `package-lock.json`.
-
-Further documentation about npm and Yarn is available at their official
-documentation pages:
-
-* [npm](https://www.npmjs.com)
-* [Yarn](https://yarnpkg.com)
-
-### The `node_modules` directory
-
-New apps list the `node_modules` directory in the app's `.gitignore` configuration,
-meaning that any changes to the contents of the directory are ignored by git.
-Using the npm configuration files allows collaborators to download your
-app source code and get the `node_modules` installed locally by executing 
-`npm install` themselves.
-
-### Effects of new dependencies on local servers
-
-When an app is being served locally, the Ember CLI will not watch for changes in the `package.json` file. Therefore, 
-if you install npm dependencies via `npm install <dependencies>`, you will 
-need to restart your Ember CLI server session manually.
-
-Dependencies installed with `ember install some-addon-name` will cause a refreash
-of a local server.
-
-### Debugging node_modules dependencies
-
-Errors such as "a module named _____ could not be found" or a colleague's report that "well, the app works on my computer but not yours!" sometimes indicate that
-the local server needs to be restarted or `node_modules` should be reinstalled.
-
-Common resolution steps are to stop the server, and then take one of these steps, and start the server again:
-
-- run `npm install` or `yarn install`
-- Delete the `node_modules` directory and run `npm install` or `yarn install`
-- Delete the `dist` directory (found in apps with versions < 3.4), delete `node_modules`, and `npm install` or `yarn install`
-- If an app uses Bower (a deprecated, npm-like tool), follow all the steps above
-in addition to deleteing `bower_components` and running `bower install`
-
-## Compiling Assets from `node_modules` and `vendor` directories
-
-Ember CLI uses the [Broccoli](https://github.com/broccolijs/broccoli) assets
-pipeline. Most Ember developers do not need to learn Broccoli, but many
-will make small changes to `ember-cli-build.js`.
-
-<!-- need to use some info from Jessica's readers question about what broccoli is -->
-
-This section covers how to manually manage dependencies.
-See [Using Addons](../../basic-use/using-addons/) and [Using NPM Packages](https://guides.emberjs.com/release/addons-and-dependencies/managing-dependencies/) for automated dependency management.
-
-To add an asset, specify the dependency in your `ember-cli-build.js` before
-calling `app.toTree()`. You can only import assets that are within the
-`node_modules` or `vendor` directories. The following example scenarios illustrate
-how this works.
-
-### Javascript Assets
-
-There are several categories of JavaScript assets, based on how
-they handle imports and exports. After identifying which type
-the asset is, follow these steps to include it in the app.
-
-#### Standard non-AMD asset as a vendor shim
-
-An ES6 shim makes a library accessible throughout the app via `import`.
-The term "shim" comes from wood working. It's a small piece of material
-used to reinforce a connection between two surfaces.
-A shim can be used to connect ES5 modules with the ES6 module
-style used in Ember.
-
-First, generate the shim:
-
-```bash
-ember generate vendor-shim moment
-```
-
-Next, provide the vendor asset path:
-
-```javascript
-app.import('vendor/shims/hamster-wheel.js');
-```
-
-Finally, use the package by adding the appropriate `import` statement:
-
-```javascript
-import Component from '@ember/component';
-import 'hamsterWheel' from 'hamster-wheel'
-
-export default Component.extend({
-  electricity() {
-    let wheel = hamsterWheel()
-    // ...
-  }
-});
-```
-
-#### Standard non-AMD asset as a global
-
-Using shims is considered best practice, to avoid polluting the global namespace.
-However, if an asset should be available anywhere in the app without using `import`,
-these are the steps to follow instead of using shims.
-
-First, provide the asset path as the first and only argument:
-
-```javascript
-app.import('vendor/path/to/hamster-wheel.js');
-```
-
-From here you would use the package as specified by its documentation, usually
-a global variable:
-
-```javascript
-import Component from '@ember/component';
-// hamsterWheel is a global variable
-
-export default Component.extend({
-  electricity() {
-    let wheel = hamsterWheel()
-    // ...
-  }
-});
-```
-
-Global variables should be added to ESLint configuration to avoid linting warnings.
-Either add `/* global myGlobalVariableName */`
-to the top of the JavaScript file that is using the variable, 
-or add it to the `globals` section in the `.eslintrc.js` file.
-
-#### Standard Named AMD Asset
-
-Provide the asset path as the first argument, and the list of modules and
-exports as the second:
-
-```javascript
-app.import('path/to/hamster-wheel/dist/named-amd/main.js');
-```
-
-<!-- we need to talk about importing a commonjs asset or an es6 asset -->
-
-To use this asset in your app, import it.
-For example, with `ic-ajax`, in order to import `ic.ajax.raw`:
-
-```javascript
-import { raw as icAjaxRaw } from 'ic-ajax';
-//...
-icAjaxRaw( /* ... */ );
-```
-
-#### Standard Anonymous AMD Asset
-
-Provide the asset path as the first argument, and the desired module name
-in the second:
-
-```javascript
-app.import('vendor/ic-ajax/dist/amd/main.js', {
-  using: [
-    { transformation: 'amd', as: 'ic-ajax' }
-  ]
-});
-```
-
-To use this asset in your app, import it.
-For example, with `ic-ajax`, to use `ic.ajax.raw`:
-
-```javascript
-import { raw as icAjaxRaw } from 'ic-ajax';
-//...
-icAjaxRaw( /* ... */ );
-```
-
-#### Environment Specific Assets
-
-If you need to use different assets in different environments, specify an
-object as the first parameter. That object's key should be the environment
-name, and the value should be the asset to use in that environment.
-
-```javascript
-app.import({
-  development: 'vendor/something-experimental.js',
-  production:  'vendor/something-stable.js'
-});
-```
-
-If you need to import an asset in one environment but not import it or any
-alternatives in other environments then you can wrap `app.import` in an `if`
-statement.
-
-```javascript
-if (app.env === 'development') {
-  app.import('vendor/something-experimental.js');
-}
-```
-
-<!-- This doesn't look like anything that's still relevant today...-->
-
-<!-- 
-##### Customizing a built-in Asset
-
-This is somewhat non-standard and discouraged, but suppose that due to a
-requirement in your application that you need to use the full version of
-Handlebars even in the production environment.  You would simply provide the
-path to the `EmberApp` constructor:
-
-```javascript
-const EmberApp = require('ember-cli/lib/broccoli/ember-app');
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, {
-    vendorFiles: {
-      'handlebars.js': {
-        production: 'bower_components/handlebars/handlebars.js'
-      }
-    }
-  });
-
-  //...
-  return app.toTree();
-};
-```
-
-Alternatively, if you want to exclude the built-in asset from being
-automatically included in `vendor.js`, you can set its value to `false`:
-
-```javascript
-const EmberApp = require('ember-cli/lib/broccoli/ember-app');
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, {
-    vendorFiles: {
-      'handlebars.js': false
-    }
-  });
-
-  //...
-  return app.toTree();
-};
-```
-
-_Note: The built-in assets are required dependencies needed by the environment
-to run your app. If you use the above method to specifically exclude
-some, you should still be including them in some other way._
--->
-
-#### Whitelisting and Blacklisting Assets
-
-You can limit which dependencies in your package.json file get imported into
-your Ember application by using the addons option of the EmberApp constructor. A
-`whitelist` parameter allows you to restrict modules to a specific list. A
-`blacklist` parameter excludes specific modules from being imported into your
-app:
-
-```javascript
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, {
-    addons: {
-      blacklist: [
-        'fastboot-app-server'
-      ]
-    }
-  });
-
-  //...
-  return app.toTree();
-};
-```
-
-#### Test Assets
-
-You may have additional libraries that should only be included when running
-tests (such as qunit-bdd or sinon). These can be imported into your app in your
-ember-cli-build.js:
-
-```javascript
-// ember-cli-build.js
-const EmberApp = require('ember-cli/lib/broccoli/ember-app');
-const isProduction = EmberApp.env() === 'production';
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, { });
-
-  if ( !isProduction ) {
-      app.import( 'path/to/sinonjs/sinon.js', { type: 'test' } );
-      app.import( 'path/to/sinon-qunit/lib/sinon-qunit.js', { type: 'test' } );
-  }
-
-  return app.toTree();
-};
-```
-
-##### Notes:
-- Be sure to pass `{ type: 'test' }` as the second argument to `app.import`.
-  This will ensure that your libraries are compiled into the `test-support.js`
-  file.
-
-## Styles
-
-### Static CSS
-
-Provide the asset path as the first argument:
-
-```javascript
-app.import('bower_components/foundation/css/foundation.css');
-```
-
-All style assets added this way will be concatenated and output as
-`/assets/vendor.css`.
-
-### Dynamic Styles (SCSS, LESS, etc)
-
-The vendor trees that are provided upon instantiation are available to your
-dynamic style files.  Take the following example (in `app/styles/app.scss`):
-
-```scss
-@import "foundation/scss/normalize.scss";
-```
-
-<!-- need to expand on this section -->
-
-## Other Assets
-
-### Using app.import()
-
-All other assets like images or fonts can also be added via `import()`. By default, they
-will be copied to `dist/` as they are.
-
-```javascript
-app.import('path/to/font-awesome/fonts/fontawesome-webfont.ttf');
-```
-
-This example would create the font file in `dist/font-awesome/fonts/fontawesome-webfont.ttf`.
-
-You can also optionally tell `import()` to place the file at a different path.
-The following example will copy the file to `dist/assets/fontawesome-webfont.ttf`.
-
-```javascript
-app.import('path/to/font-awesome/fonts/fontawesome-webfont.ttf', {
-  destDir: 'assets'
-});
-```
-
-If you need to load certain dependencies before others, you can set the
-`prepend` property equal to `true` on the second argument of `import()`. This
-will prepend the dependency to the vendor file instead of appending it, which
-is the default behavior.
-
-```javascript
-app.import('path/to/es5-shim/es5-shim.js', {
-  type: 'vendor',
-  prepend: true
-});
-```
-
-If you need some of your assets to be included into specific file you can
-provide an `outputFile` option for your import:
-
-```javascript
-// ember-cli-build.js
-app.import('vendor/dependency-1.js', { outputFile: 'assets/additional-script.js'});
-app.import('vendor/dependency-2.js', { outputFile: 'assets/additional-script.js'});
-```
-
-As a result both dependencies will end up in `dist/assets/additional-script.js`
-in the same order they were specified.
-
-_Note: `outputFile` works only for JavaScript and css files._
-
-<!-- Should info this old be kept somewhere centralized? -->
-
-<!-- 
-##### Using broccoli-funnel
-
-With the [broccoli-funnel](https://github.com/broccolijs/broccoli-funnel)
-package, (parts of) a bower-installed package can be used as assets as-is.
-First ensure that the Broccoli
-package needed to build is installed:
-
-```bash
-npm install broccoli-funnel --save-dev
-```
-
-Add this import to the top of `ember-cli-build.js`, just below the `EmberApp` require:
-
-```javascript
-const Funnel = require('broccoli-funnel');
-```
-
-Within `ember-cli-build.js`, we merge assets from a bower dependency with the main app tree:
-
-```javascript
-const EmberApp = require('ember-cli/lib/broccoli/ember-app');
-const Funnel = require('broccoli-funnel');
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, { });
-
-  // Copy only the relevant files. For example the WOFF-files and stylesheets for a webfont:
-
-  let extraAssets = new Funnel('bower_components/a-lovely-webfont', {
-     srcDir: '/',
-     include: ['**/*.woff', '**/stylesheet.css'],
-     destDir: '/assets/fonts'
-  });
-
-  // Providing additional trees to the `toTree` method will result in those
-  // trees being merged in the final output.
-
-  return app.toTree(extraAssets);
-};
-```
-
-In the above example the assets from the fictive bower dependency called `a-lovely-webfont` can now
-be found under `/assets/fonts/`, and might be linked to from `index.html` like so:
-
-```html
-<link rel="stylesheet" href="assets/fonts/lovelyfont_bold/stylesheet.css">
-```
-
-You can exclude assets from the final output in a similar fashion. For example,
-to exclude all `.gitkeep` files from the final output:
-
-```javascript
-// Again, add this import to the top of `ember-cli-build.js`, just below the `EmberApp` require:
-const EmberApp = require('ember-cli/lib/broccoli/ember-app');
-const Funnel = require('broccoli-funnel');
-
-module.exports = function(defaults) {
-  let app = new EmberApp(defaults, { });
-
-  // Filter toTree()'s output
-  let filteredAssets = new Funnel(app.toTree(), {
-    // Exclude gitkeeps from output
-    exclude: ['**/.gitkeep']
-  });
-
-  // Export filtered tree
-  return filteredAssets;
-};
-```
-
-_Note: [broccoli-static-compiler](https://github.com/joliss/broccoli-static-compiler) is deprecated. Use [broccoli-funnel](https://github.com/broccolijs/broccoli-funnel) instead._
--->
diff --git a/guides/legacy/index.md b/guides/legacy/index.md
deleted file mode 100644
index e44e3f5..0000000
--- a/guides/legacy/index.md
+++ /dev/null
@@ -1,3 +0,0 @@
-<!-- This is only here because it is required. -->
-
-[Asset Compilation](./asset-compilation)
diff --git a/guides/pages.yml b/guides/pages.yml
index b9e962c..1e28ff0 100644
--- a/guides/pages.yml
+++ b/guides/pages.yml
@@ -13,45 +13,43 @@
       url: 'cli-commands'
     - title: 'Using addons'
       url: 'using-addons'
+    - title: 'Assets and dependencies'
+      url: 'assets-and-dependencies'
     - title: 'Deploying an Ember app'
       url: 'deploying'
     - title: 'Upgrading'
       url: 'upgrading'
 
+- title: 'Advanced use'
+  url: 'advanced-use'
+  pages:
+  - title: 'Overview'
+    url: 'index'
+  - title: 'Asset Compilation'
+    url: 'asset-compilation'
+  - title: 'Stylesheet compilation'
+    url: 'stylesheets'
+  - title: 'Creating blueprints'
+    url: 'blueprints'
+
 - title: 'Writing addons'
   url: 'writing-addons'
   pages:
   - title: 'Addon structure'
     url: 'index'
-  - title: 'Tutorial'
-    url: 'tutorial'
-  - title: 'Testing'
-    url: 'testing'
+  - title: 'Tutorial - writing your first addon'
+    url: 'intro-tutorial'
   - title: 'Writing documentation'
     url: 'documenting'
-  - title: 'Deploying an addon'
-    url: 'deploying'
-  - title: 'Wrapping existing libraries'
-    url: 'wrappers'
 
-- title: 'Advanced use'
-  url: 'advanced-use'
+- title: 'API Documentation'
+  url: 'api-documentation'
   pages:
   - title: 'Overview'
     url: 'index'
-  - title: 'Advanced configurations'
-    url: 'configurations'
-  - title: 'Broccoli asset pipeline'
-    url: 'asset-pipeline'
-  - title: 'Creating blueprints'
-    url: 'blueprints'
-  - title: 'Stylesheet compilation'
-    url: 'stylesheets'
-  - title: 'File layout and the resolver'
-    url: 'file-layout'
 
-- title: 'Reference'
-  url: 'reference'
+- title: 'Appendix'
+  url: 'appendix'
   pages:
   - title: 'Overview'
     url: 'index'
@@ -61,19 +59,4 @@
     url: 'dev-tools'
   - title: 'Common issues'
     url: 'common-issues'
-  - title: 'Frequently Asked Questions'
-    url: 'faq'
-
-- title: 'API Documentation'
-  url: 'api-documentation'
-  pages:
-  - title: 'Overview'
-    url: 'index'
 
-- title: 'Ported but needs editing and reorganizing'
-  url: 'legacy'
-  pages:
-    - title: 'Asset Compilation'
-      url: 'asset-compilation'
-    - title: 'Managing Dependencies'
-      url: 'dependencies'
diff --git a/guides/reference/faq.md b/guides/reference/faq.md
deleted file mode 100644
index 85b1d6a..0000000
--- a/guides/reference/faq.md
+++ /dev/null
@@ -1 +0,0 @@
-<!-- Do I need to use the CLI, why broccoli instead of webpack, node version compatibility? -->
diff --git a/guides/reference/index.md b/guides/reference/index.md
deleted file mode 100644
index 2ae8382..0000000
--- a/guides/reference/index.md
+++ /dev/null
@@ -1 +0,0 @@
-<!-- Brief description of what goes in the reference section. Mostly edge case stuff -->
diff --git a/guides/writing-addons/documenting.md b/guides/writing-addons/documenting.md
index 32c64fc..5ca1be4 100644
--- a/guides/writing-addons/documenting.md
+++ b/guides/writing-addons/documenting.md
@@ -1 +1,37 @@
-<!-- Should mention that many authors use the dummy app for their documentation. Should link to ember-cli-addon-docs, with clear indication of its status as a community project -->
+An important part of writing an addon is showing others how to use it.
+There are some well-established patterns and tools that help addon authors save some time and get their work discovered.
+
+## Naming your addon
+
+There is no enforced rule for it, but most addons use `ember` as the first part of the addon's name.
+This makes the addon easier to search for in the [npm repository](https://www.npmjs.com/search?q=ember).
+
+## The README
+
+Every addon should have a `README.md` file describing why someone might want to use the addon, installation instructions, how to run tests, and contributing guidelines.
+If your addon has a documentation site or demo apps, be sure to include links to them.
+
+## Creating a documentation site
+
+[ember-cli-addon-docs](https://ember-learn.github.io/ember-cli-addon-docs/) help you create interactive, versioned documentation for your addon!
+
+This tool is used by both Ember projects and the community as a whole.
+For example, check out the [ember-styleguide](https://github.com/ember-learn/ember-styleguide), which is a library of UI components that make up [emberjs.com](https://emberjs.com). The addon docs help show what components are available and how to use them.
+
+Another option is to create your own site from scratch.
+Many addon authors use the dummy app within an addon to build their documentation site, and deploy it to GitHub pages.
+
+For more inspiration, take a look at how your favorite addons do their documentation.
+
+## Getting an addon included in Ember Observer
+
+[Ember Observer](https://www.emberobserver.com/) is an independent, community-made resource that rates and lists addons.
+
+When you create an addon using the Ember CLI, it includes tags in the `package.json` that help it get picked up for inclusion in Ember Observer. There are objective and subjective evaluations that factor into an addon's overall score and ranking. Read more about the scoring [here](https://www.emberobserver.com/about).
+
+## Following semver
+
+Following [Semver](https://semver.org/), or Semantic Versioning, is highly encouraged for addon authors. It is the main way to inform an addon's users of breaking changes, new features, and patches.
+
+When there are major versions with breaking changes, it is important to include notes about how users can migrate to new versions.
+Depending on the extent of the breaking changes, the migration steps often have a summary in the `README` and a link to more detailed information in the release notes.
diff --git a/guides/writing-addons/tutorial.md b/guides/writing-addons/intro-tutorial.md
similarity index 100%
rename from guides/writing-addons/tutorial.md
rename to guides/writing-addons/intro-tutorial.md
diff --git a/guides/writing-addons/testing.md b/guides/writing-addons/testing.md
index ebbb985..c5b8cf0 100644
--- a/guides/writing-addons/testing.md
+++ b/guides/writing-addons/testing.md
@@ -1 +1,3 @@
+<!-- This page is not included in the table of contents and therefore not part of the build yet -->
+
 <!-- Should cover ember-try, tests, and using the dummy app in testing. See ember-styleguide and popular addons for inspiration -->