diff --git a/packages/ember-routing/lib/system/dsl.js b/packages/ember-routing/lib/system/dsl.js
index a3183fea969..dcc0b8e5111 100644
--- a/packages/ember-routing/lib/system/dsl.js
+++ b/packages/ember-routing/lib/system/dsl.js
@@ -25,9 +25,8 @@ DSL.prototype = {
       options = {};
     }
 
-    var type = options.resetNamespace === true ? 'resource' : 'route';
     Ember.assert(
-      `'${name}' cannot be used as a ${type} name.`,
+      `'${name}' cannot be used as a route name.`,
       (function() {
         if (options.overrideNameAssertion === true) { return true; }
 
diff --git a/packages/ember-routing/lib/system/router.js b/packages/ember-routing/lib/system/router.js
index c002de6a146..2815055a911 100644
--- a/packages/ember-routing/lib/system/router.js
+++ b/packages/ember-routing/lib/system/router.js
@@ -921,14 +921,36 @@ EmberRouter.reopenClass({
     in your application. These mappings are defined within the
     supplied callback function using `this.route`.
 
+    The first parameter is the name of the route which is used by default as the
+    path name as well.
+
+    The second parameter is the optional options hash. Available options are:
+      * `path`: allows you to provide your own path as well as mark dynamic
+        segments.
+      * `resetNamespace`: false by default; when nesting routes, ember will
+        combine the route names to form the fully-qualified route name, which is
+        used with `{{link-to}}` or manually transitioning to routes. Setting
+        `resetNamespace: true` will cause the route not to inherit from its
+        parent route's names. This is handy for resources which can be accessed
+        in multiple places as well as preventing extremely long route names.
+        Keep in mind that the actual URL path behavior is still retained.
+
+    The third parameter is a function, which can be used to nest routes.
+    Nested routes, by default, will have the parent route tree's route name and
+    path prepended to it's own.
+
     ```javascript
     App.Router.map(function(){
-      this.route('about');
-      this.route('article', { resetNamespace: true });
+      this.route('post', { path: '/post/:post_id' }, function() {
+        this.route('edit');
+        this.route('comments', { resetNamespace: true }, function() {
+          this.route('new');
+        });
+      });
     });
     ```
 
-    For more detailed examples please see
+    For more detailed documentation and examples please see
     [the guides](http://emberjs.com/guides/routing/defining-your-routes/).
 
     @method map
diff --git a/packages/ember-routing/tests/system/dsl_test.js b/packages/ember-routing/tests/system/dsl_test.js
index 7bb4d80fab5..cdfc33a2559 100644
--- a/packages/ember-routing/tests/system/dsl_test.js
+++ b/packages/ember-routing/tests/system/dsl_test.js
@@ -39,7 +39,7 @@ QUnit.test('should fail when using a reserved route name', function() {
 
       var router = Router.create();
       router._initRouterJs();
-    }, `'${reservedName}' cannot be used as a resource name.`);
+    }, `'${reservedName}' cannot be used as a route name.`);
 
   });
 });