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.