Ember Data Docs

ember-data.md

Ember Data

In general, I would say that the documentation could improve simply from being a lot more explicit about the particular details that are important when using Ember Data:

• What are the actual conventions Ember Data is expecting your API to adhere to?
• If your API is not following them, what are the steps you can take to override the defaults to get on the happy path? In practice these are pretty easy which is great, but it is not terribly obvious to users.
• The answers to these questions exist in the current docs, but they require a lot of navigating around the site.
• Where are the ember data docs? They are implied when reading the Ember model docs, but it should be a lot easier and more clear, shouldn't it?
• The Ember guides assume you are using Ember Data, but that is not made explicit in any way.
• Most common issue is that the RESTAdapter needs to be extended to massage api data into format the ember expects. This should be a lot easier to determine based on the docs.
• How to work with and extend adapters is likely the most common ember data issue?
• Make things more clear. For example, what are the conventions mentioned below?

Without any configuration, Ember Data can load and save records and their relationships served via a RESTful JSON API, provided it follows certain conventions.

Features

• Basic CRUD. Challenges arise when trying to create anything with relationships.

Next steps

In general, I think Brendan's branch is a great start, it just needs some updates.

One general note is that the introduction briefly touches on how you don't need to use Ember Data to work with Models, but then all subsequent documentation revolves around using Ember Data. Seems like this could be owned more explicitly.

Introduction

• On the Models introduction page, make Ember Data more prominent (maybe with its own heading?)
• I think it would make sense to have the introduction section only introduce Models and the existence of Ember Data, but the core concepts section could be its own page under an Ember Data heading.
• If a user is not going to use Ember Data, do we assume they know what they are doing?

Defining Models

• It seems redundant on this page to specify Ember Data as a dependency when it is mentioned as a part of ember-cli in the Intro page

FAQ

• Create a TOC to allow for better navigation of this section