More novice friendly + instruction steps now lead to predictable outcome (working docs site)

Author: bravo-kernel

tests/dummy/app/pods/docs/quickstart/template.md

@@ -1,34 +1,38 @@
 # Quickstart
 
-This quickstart guide will get you going with a docs site for your brand new addon.
+This quickstart guide will get you started with a docs site for your brand new
+addon. After completion you will have a docs homepage, a docs subpage named
+`installation`, an automatically generated API reference and a marketing
+homepage you can use to promote your addon.
 
-1. **Install the addon.**
+1. **Install Addon Docs.**
 
   ```
   ember install ember-cli-addon-docs
   ```
 
-2. **Add the required routes.** Open `tests/dummy/app/router.js` and add the following route definitions:
+2. **Add the docs routes.** Open `tests/dummy/app/router.js` and add the
+following route definitions to your main route.
 
   {{#docs-snippet name='quickstart-router.js' title='tests/dummy/app/router.js'}}
-    this.route('docs', function() {
-      this.route('api', function() {
-        this.route('item', { path: '/*path' });
+    this.route('docs', function() { // docs homepage (required)
+      this.route('installation'); // docs subpage
+      this.route('api', function() { // autogenerated API homepage (required)
+        this.route('item', { path: '/*path' }); // autogenerated API subpages (required)
       });
     });
   {{/docs-snippet}}
 
-3. **Create your app skeleton.** You can add the global keyboard shortcuts component to enable keyboard navigation around your docs site (use `?` to show the help window). Here's our application template:
+3. **Create your docs skeleton.** Create a new template for the `docs` route
+and make sure it contains the `DocsViewer` component and navigation items for
+all docs pages in your site.
 
-  {{docs-snippet name="docs-demo-application-template.hbs" title="tests/dummy/app/templates/application.hbs"}}
-
-4. **Create your docs skeleton.** Create a template for the `docs` route and add the DocsViewer component.
-
-  {{#docs-snippet name='quickstart-skeleton.hbs' title='tests/dummy/app/pods/docs/template.hbs'}}
+  {{#docs-snippet name='quickstart-skeleton.hbs' title='tests/dummy/app/templates/docs.hbs'}}
     {{#docs-viewer as |viewer|}}
 
       {{#viewer.nav as |nav|}}
-        {{nav.item 'Overview' 'docs.index'}}
+        {{nav.item 'Introduction' 'docs.index'}}
+        {{nav.item 'Installation' 'docs.installation'}}
       {{/viewer.nav}}
 
       {{#viewer.main}}
@@ -42,15 +46,36 @@ This quickstart guide will get you going with a docs site for your brand new add
     {{/docs-viewer}}
   {{/docs-snippet}}
 
-5. **Fill out the index of your docs page.** We called it Overview but you can call it whatever you want. Since Addon Docs supports markdown templates out of the box, we can make this a Markdown file.
+4. **Create your documentation sources.** Documentation sources contain the
+actual documentation for your addon and live in the folder
+`tests/dummy/app/templates/docs`. Since Addon Docs supports Markdown out
+of the box we will create two `.md` files (one for your docs `index` and one
+for the `installation` page).
 
-  {{#docs-snippet name='quickstart-markdown.md' title='tests/dummy/app/templates/docs/index.md' language='markdown'}}
-    # Overview
+  {{#docs-snippet name='quickstart-markdown-index.md' title='tests/dummy/app/templates/docs/index.md' language='markdown'}}
+    # Index
 
     This is my new addon, and it rocks!
   {{/docs-snippet}}
 
-6. **Add a 404 route.** Add a route to the end of your router and create an associated template.
+  {{#docs-snippet name='quickstart-markdown-subpage.md' title='tests/dummy/app/templates/docs/installation.md' language='markdown'}}
+    # Installation
+
+    So easy to install and configure, sweet!
+  {{/docs-snippet}}
+
+5. **Create your marketing homepage**. Create a new template that will function
+as the marketing homepage for your new addon.
+
+  {{#docs-snippet name='quickstart-marketing-index.hbs' title='tests/dummy/app/templates/index.hbs'}}
+    {{#link-to 'docs'}}Docs{{/link-to}}
+    {{#link-to 'docs.api'}}API Reference{{/link-to}}
+
+    My addon marketing page with mind-blowing demo.
+  {{/docs-snippet}}
+
+6. **Add a 404 route.** Add the following route to the end of your router and
+create the associated template.
 
   {{#docs-snippet name='quickstart-404.js' title='tests/dummy/app/router.js'}}
     this.route('not-found', { path: '/*path' });
@@ -63,28 +88,29 @@ This quickstart guide will get you going with a docs site for your brand new add
     </div>
   {{/docs-snippet}}
 
-8. **Add more docs pages.** It's up to you how to structure your docs - use the Snippet, Viewer and Demo components to help you write your documentation. Let's add another page to ours: we'll add the route, link to our docs viewer, and the actual template.
+7. **Launch your docs site**. Run `ember serve` and browse to
+`localhost:4200/docs` to enjoy your brand new documentation website.
 
-  {{#docs-snippet name='quickstart-more-docs.js' title='tests/dummy/app/router.js'}}
-    this.route('docs', function() {
-      this.route('installation');
-    });
-  {{/docs-snippet}}
+8. **Create more pages.** To add more doc pages simply follow the same steps as
+used for the `Installation` page in above instructions:
 
-  {{#docs-snippet name='quickstart-more-nav.hbs' title='tests/dummy/app/templates/docs.hbs'}}
-    {{#viewer.nav as |nav|}}
-      {{nav.item 'Installation' 'docs.installation'}}
-    {{/viewer.nav}}
-  {{/docs-snippet}}
+  - create a docs subroute
+  - add a navigation item to the `docs` template
+  - create a new documentation source file (using Markdown, HtmlBars, etc.)
 
-  {{#docs-snippet name='quickstart-installation-readme.md' title='tests/dummy/app/templates/docs/installation.md'}}
-    # Installation
+## Optional
 
-    To install My Addon, run...
-  {{/docs-snippet}}
+1. **Keyboard navigation.** You may want to enable keyboard navigation for your
+docs site by adding the `DocsKeyboardShortcuts` component to your dummy
+application template. Once enabled you can use `?` to show the navigation help
+windows.
 
-8. **Round out your site.**
+  {{docs-snippet name="docs-demo-application-template.hbs" title="tests/dummy/app/templates/application.hbs"}}
 
-* **Add a favicon to your dummy app.** We recommend using [Ember CLI Favicon](https://github.com/davewasmer/ember-cli-favicon).
+2. **Optional: add a favicon.** You may want to place a favicon in the
+`tests/dummy/public` folder. We recommend using using
+ [Ember CLI Favicon](https://github.com/davewasmer/ember-cli-favicon).
 
-* **Install [Ember Router Scroll](https://github.com/dollarshaveclub/ember-router-scroll).**
+3. **Optional: better scrolling.** You may want to install
+[Ember Router Scroll](https://github.com/dollarshaveclub/ember-router-scroll)
+to enable "scroll to top with preserved browser history scroll position".