docs: internal linking and organization

chriskrycho · chriskrycho · commit ee8fae912da6 · 2020-11-23T19:11:13.000-07:00
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -27,7 +27,6 @@
   * [Mixins](legacy/mixins.md)
   * [Computed Properties](legacy/computed-properties.md)
   * [EmberObject](legacy/ember-object.md)
-  * [Legacy Ember Guide](legacy/overview.md)
 * [Upgrading from 1.x](upgrade-notes.md)
 * [Troubleshooting](troubleshooting/README.md)
   * [Conflicting Type Dependencies](troubleshooting/conflicting-types.md)
diff --git a/docs/ember-data/README.md b/docs/ember-data/README.md
@@ -1,2 +1,6 @@
 # Working With Ember Data
 
+In this section, we cover how to use TypeScript effectively with specific Ember Data APIs \(anything you'd find under the `@ember-data` package namespace\).
+
+We do _not_ cover general usage of Ember Data; instead, we assume that as background knowledge. Please see the Ember Data [Guides](https://guides.emberjs.com/release/models) and [API docs](https://api.emberjs.com/ember-data/release)!
+
diff --git a/docs/ember-data/overview.md b/docs/ember-data/overview.md
diff --git a/docs/ember/README.md b/docs/ember/README.md
@@ -1,2 +1,6 @@
 # Working With Ember
 
+In this section, we cover how to use TypeScript effectively with specific Ember APIs \(anything you'd find under the `@ember` package namespace\).
+
+We do _not_ cover general usage of Ember; instead, we assume that as background knowledge. Please see the Ember [Guides](https://guides.emberjs.com/release/) and [API docs](https://api.emberjs.com/ember/release)!
+
diff --git a/docs/ember/controllers.md b/docs/ember/controllers.md
@@ -1,6 +1,6 @@
 # Controllers
 
-Like [routes](https://github.com/typed-ember/ember-cli-typescript/tree/3a434def8b8c8214853cea0762940ccedb2256e8/docs/ember/routes/README.md), controllers are just normal classes with a few special Ember lifecycle hooks and properties available.
+Like [routes](./routes.md), controllers are just normal classes with a few special Ember lifecycle hooks and properties available.
 
 The main thing you need to be aware of is special handling around query params. In order to provide type safety for query param configuration, Ember's types specify that when defining a query param's `type` attribute, you must supply one of the allowed types: `'boolean'`, `'number'`, `'array'`, or `'string'` \(the default\). However, if you supply these types as you would in JS, like this:
 
diff --git a/docs/ember/overview.md b/docs/ember/overview.md
diff --git a/docs/legacy/README.md b/docs/legacy/README.md
@@ -1,2 +1,9 @@
 # Working With Ember Classic
 
+We emphasize the happy path of working with Ember in the [Octane Edition](https://emberjs.com/editions/octane/). However, there are times you’ll need to understand these details:
+
+1. Most existing applications make heavy use of the pre-Octane \(“legacy”\) Ember programming model, and we support that model—with caveats.
+2. Several parts of Ember Octane \(specifically: routes, controllers, services, and class-based helpers\) continue to use these concepts under the hood, and our types support that—so understanding them may be important at times.
+
+The rest of this guide is dedicated to helping you understand how `ember-cli-typescript` and the classic Ember system interact.
+
diff --git a/docs/legacy/overview.md b/docs/legacy/overview.md
diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md
@@ -1 +1,7 @@
 # Troubleshooting
+
+Stuck with something? Hopefully one of the documents below can help. If not, file an issue on GitHub and we'll try to help you get it sorted (and it may end up in here).
+
+## Outline
+
+* [Conflicting Type Dependencies](./conflicting-types.md)
