docs: improve Decorators page content

- add a better introductory sentence
- improve the paragraphing between lists
- add missing links to pages

Author: chriskrycho

docs/SUMMARY.md

@@ -8,7 +8,7 @@
   * [Decorators](ts/decorators.md)
   * [Current limitations](ts/current-limitations.md)
   * [Building Addons in TypeScript](ts/with-addons.md)
-  * [Understanding the Package Names](ts/package-names.md)
+  * [Understanding the `@types` Package Names](ts/package-names.md)
 * [Working With Ember](ember/README.md)
   * [Components](ember/components.md)
   * [Services](ember/services.md)

docs/ts/README.md

@@ -12,4 +12,4 @@ This guide covers the common details and "gotchas" of using TypeScript with Embe
 * [Decorators](decorators.md)
 * [Current limitations](current-limitations.md)
 * [Building Addons in TypeScript](with-addons.md)
-* [Understanding the Package Names](package-names.md)
+* [Understanding the `@types` Package Names](package-names.md)

docs/ts/decorators.md

@@ -1,19 +1,21 @@
 # Decorators
 
-There are three important points that apply to _all_ decorator usage in Ember:
+Ember makes heavy use of decorators, and TypeScript does not currently support deriving type information from decorators.
+
+As a result, there are three important points that apply to _all_ decorator usage in Ember:
 
 1. Whenever using a decorator to declare a class field the framework sets up for you, you should mark it with `declare`. That includes all service and controller injections as well as all Ember Data attributes and relationships.
 
    Normally, TypeScript determines whether a property is definitely not `null` or `undefined` by checking what you do in the constructor. In the case of service injections, controller injections, or Ember Data model decorations, though, TypeScript does not have visibility into how instances of the class are _initialized_. The `declare` annotation informs TypeScript that something outside its
 
 2. For Ember Data Models, you will need to use the optional `?` operator on field declarations if the field is optional \(`?`\). See the Ember Data section of the guide for more details!
+
 3. You are responsible to write the type correctly. TypeScript does not currently use decorator information at all in its type information. If you write `@service foo` or even `@service('foo') foo`, _Ember_ knows that this resolves at runtime to the service `Foo`, but TypeScript does not and—for now—_cannot_.
 
    This means that you are responsible to provide this type information, and that you are responsible to make sure that the information remains correct and up to date
 
-For examples, see the detailed discussions of each place decorators are used in the framework:
+For examples, see the detailed discussions of the two main places decorators are used in the framework:
 
-* Ember Services
-* Ember Controllers
-* Ember Data Models
+* [Services](../ember/services.md)
+* [Ember Data Models](../ember-data/models.md)
 

docs/ts/package-names.md

@@ -1,4 +1,4 @@
-# Understanding the Package Names
+# Understanding the `@types` Package Names
 
 You may be wondering why the packages added to your `package.json` and described in [**Installation: Other packages this addon installs**](https://github.com/typed-ember/ember-cli-typescript/tree/3a434def8b8c8214853cea0762940ccedb2256e8/docs/README.md#other-packages-this-addon-installs) are named things like `@types/ember__object` instead of something like `@types/@ember/object`. This is a conventional name used to allow both the compiler and the [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) publishing infrastructure \([types-publisher](https://github.com/Microsoft/types-publisher)\) to handle scoped packages, documented under [**What about scoped packages?**](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master#what-about-scoped-packages) in [the DefinitelyTyped README](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master).