Add documention clarifying use of scenarios (#1427)

tests/dummy/app/pods/docs/advanced/switching-between-scenarios/template.md

@@ -0,0 +1,66 @@
+# Switching between scenarios
+
+You can use the scenarios directory to organize your scenario files. Scenarios
+might be useful if you need to conduct [user acceptance testing](https://en.wikipedia.org/wiki/Acceptance_testing#User_acceptance_testing)
+of your application using Mirage data. For example, you might test whether a user 
+can complete a set of tasks specific to unique circumstances defined in a scenario.
+
+Currently, scenarios are not a first-class API: Mirage only uses the default scenario
+in your development environment.
+
+That said, you can still configure your default scenario file to honor options passed
+to the runtime environment. For example, if you created a scenario file called `some-scenario.js`
+and wanted to load that scenario based on an environment variable called `MIRAGE_SCENARIO`, you
+could add the following to `scenarios/default.js`:
+
+```js
+import { camelize } from '@ember/string';
+import ENV from '../../config/environment';
+
+export default function(server) {
+  const { MIRAGE_SCENARIO = '' } = ENV;
+  const scenario = server._config.scenarios[camelize(MIRAGE_SCENARIO)];
+
+  if (scenario) {
+    scenario(server);
+  }
+
+  // plus whatever default scenario code you want
+}
+
+```
+
+You would also need to pull the environment variable into your `environment/config.js`:
+
+```js
+const { MIRAGE_SCENARIO } = process.env.MIRAGE_SCENARIO;
+
+module.exports = function(environment) {
+  const ENV = {
+    // ...other stuff
+
+    MIRAGE_SCENARIO,
+
+    // ...other stuff
+  };
+
+  return ENV;
+}
+```
+
+Finally, you could switch between scenario files on the command line:
+
+```bash
+MIRAGE_SCENARIO=some-scenario ember s
+```
+
+Like other Mirage objects, all scenario files must export a function like so:
+
+```js
+export default function(server) {
+  // server.createList('post', 15);
+}
+```
+
+Note that the `server` parameter is not provided by default.
+

tests/dummy/app/pods/docs/template.hbs

@@ -29,6 +29,7 @@
     {{nav.item "Environment options" "docs.advanced.environment-options"}}
     {{nav.item "Simulating cookie responses" "docs.advanced.simulating-cookie-responses"}}
     {{nav.item "Mocking GUIDs" "docs.advanced.mocking-guids"}}
+    {{nav.item "Switching between scenarios" "docs.advanced.switching-between-scenarios"}}
     {{nav.item "Customizing the inflector" "docs.advanced.customizing-the-inflector"}}
 
   {{/viewer.nav}}

tests/dummy/app/router.js

@@ -41,6 +41,7 @@ Router.map(function() {
       this.route('simulating-cookie-responses');
       this.route('mocking-guids');
       this.route('customizing-the-inflector');
+      this.route('switching-between-scenarios');
     });
 
     this.route('api', function() {