Ideas for Improving the Getting Started Experience

I don’t disagree about reducing the flood of information, but I would still prefer to see the generated objects within the sample code, as well as an explanation. Ideally, a button to show/hide generated code would be fantastic.

I would really like to see the “magic” behind the scenes of ember. As a part of the Getting Started guide, I think the author should mention when and where the magic is invoked. Every one expects a MVC framework to use a model, view and controller but in many cases Ember doesn’t require a controller.

There is a good naming conventions guide - http://emberjs.com/guides/concepts/naming-conventions/ and that should be referenced.

I would cast a vote for medior level examples.

Looking on the web there are quite some examples for getting started, you just need to keep an eye on the date it was written. As soon as you’re past that stage it becomes more difficult.

For me, having actual use cases for common scenarios with either some documentation or links to 3rd party tutorials and code would be extremely helpful.

For example, I’ve barely started on an app and already I’m stumped by things that I feel should be simple:

  • Authentication
  • Modals/Overlays (controllers/views that can be shown irrespective of current route)
  • Polymorphic associations
2 Likes

As I’m a fresh Ember adaptor (1 week in), my memories are fresh regarding what challenged/challenges me to grasp Ember. As a further note, I’m coming from a server-side Java Spring Framework background.

I tried understanding Ember by reading emberjs.com/guides/ from top to bottom. I gave up half-way through.

There are several ways of how to present any concept (such as “Ember” is a concept). The way that guide is written is not adapted to the way I learn (maybe for others that guide is very helpful, but unfortunately it is not for me).

Here are three suggestions that I think could help a beginner like me:

  • The current Ember guide introduces many concepts (controllers, views, templates, routers, models…) without giving me a chance of putting these concepts into context. It’d be great if there was a graphical diagram of all these concept, with this diagram putting all concepts visually into context. As an example, take a look at Spring MVC’s documentation. While those diagrams there can still be improved, during my Spring MVC learning time, these diagrams acted as “maps” to test learning hypotheses against. … With what I have learned about Ember yet, I can’t mentally draw a conceptual and contextual diagram yet - because, for example, I haven’t understood how Ember.Route and Ember.Router fit contextually within all the other Ember.* things.

  • Help beginners with their mental migration. I’m coming from Java/Spring, using that server-side. Now I start using Javascript/Ember client-side. I want to marry Spring with Ember. Ember uses the term Model throughout its guide. The Java world also uses the term Model. But both worlds understand different things with this homonymous term. Having some broad overview where most of your users come from, I guess it would be beneficial to say what concept x is not and what it should not be confused with. An example statement could be then:

“Ember’s understanding of “model” is different from a Java world’s understanding of “model”. While in Java, a model (of some domain) typically is understood as a collection of classes and their interactions, in Ember a “model” is …”

  • Be explicit about the magic going on in Ember. Yes, convention over configuration helps with focusing and getting things done faster. But where magic happens is a vital thing to know even for a beginner. An example: Yesterday, I created an Ember application with App = Ember.Application.create(); . It works … I’m moving on… Today, I created an Ember application with app = Ember.Application.create();. It doesn’t work. Why? Because, using try and error, I found out an Ember application’s name has to start with a capital letter. This is magic that I had to learn through reverse engineering (which costs time and produces frustration). If one doesn’t know about all the magic, sooner or later one will trip over weird behavior and riddle why the application behaves unexpectedly.

I hope my three suggestions can help.

6 Likes

I’m a beginner who’s spent the last week banging his head against Ember. While there have been moments of sheer splendour there have also been many hours of frustration. Some things just work — despite all the dire warnings I’ve found ember-data to work fine (once I found and buit the correct version that exactly matched the corresponding version of Ember). I think the main problem I’m having is that there are many thing in Ember that are non-obvious to an outsider that would be obvious if only there was someone to ask a few questions to. I’ve been surprised at how difficult I’ve found much of it.

Here’s braindump of things I think would make my life easier.

1) A Beginners’ Discuss

I think a beginners’ Discuss would be a good idea — at least for a while. Stack Exchange is all very well for people searching for specific incantation but it’s not agreat place to ask a quick, possibly vague, question. If you had a discuss where it was assumed that the questions would be dumb and sometimes vague and where the same questions gets could be asked over and over it would be useful to people like me who would just like a quick pointer to how to tackle something in an Ember-y way. Plus it would be a great recource for the Ember team to see which questoin come up again and again. The rules would, obviously, have to allow people to ask anything without fear of a RTFM response. Hopefully a comunity of people who like to answer beginner’s questions would soon form around it.

2) Improvements to the docs

Here’s a few things I’ve been befuddled by:

Sharing internal state & data

Specifically around the issue of what goes where, who has what and how each part communicates with the others. The real conceptual difficulties I’m having is around sharing data between objects. How to I get the current active route from the router? How would I give that to a view that displays a nav menu? How would I make a pop-up window with it’s own state? Are there global properties that can be interogated? Are there global objects with properties that I can use? Should I?

Actions & Events (and Views and Controllers)

It’s not fully clear I think what the difference between an action and an event is and why events go to methods on the View but actions go to methods on the Controller. I’m still al bit fuzzy about what the seperate view is for.

Routes that aren’t necessarily URLs or URL like

I’m still unclear about quite how things like pop-up windows should be wired into an Ember application. Are they routes? If routes are more about program state and models then should they be used for things that aren’t URL-y?

Debugging One of the biggest problems I’ve had is trying to get Ember to produce useful stuff my my console. Partly this is because Ember components seem quite complex so even though I may log an Object I can poke around in the internals don’t make much sense to me. Also asynchronicity makes knowing where log stuff equally tricky.

“Do-it-like-this” (and an expanded “What do I use when?”)

Where things can be done in a multitude of ways it would be great to have explaination and advice about which is the best to use. E.g. should I be declaring things like store inside my Application.create function (as is done in the example usage of the Ember.Application class) or in or with an DS.Store.extend method as is shown in the guide?

Automagic

Areas of the docs that explain what ‘Automatic’ stuff will go on with each thing would be very useful. “If you don’t supply one of these Ember will supply one for you” kind’a stuff also “if you have one of the you need one of these”. I’m stil confused about a lot of this ‘magic-y’ stuff. Again, the “Naming Conventions” part of the guide is great for this.

More Naming Explanations

E.g. Upper-case magic. The “Naming Conventions” is great for a lot of stuff but it doesn’t mention the magic of case in Ember. Also, If I create a controller with the correct name will it automagically attach to a corresponding view? What if that view is a subview?

Widgets

The main reason I am atracted to Ember is it’s ability to create small, encapsulated, re-usable UI elements. It would be great to see a couple of examples of how best to do this kind of thing and perhaps at least one example of wiring up a widget that works with Bootstrap (as I’m sure many people will be prototyping with it). Examples with views with a few interacting elements and events would be enough to demonstrate the core principals.

Compiling Templates

A simple explanation of how best to do this would be good. A simple single-use tool would be great.

3) Step-by-step guide app

I’d like to see someone build a tiny app up step-by-step with explanations for what each part does and why it is needed. The “Naming Conventions” part of the Guide is good for learning this but I’d find an app that can be built and run at each stage invaluable. I’m finding knowing which bits have to be added together for the whole to work tricky. A bunch of minimal but genuinely ordinary (in a web-app sense) stuff would be best: a blog or an image gallery showing how to create, update and delete things while showing what advantage Ember is giving this over traditional server-based approach. There’s only so many abstract, unattached explanations that can be held in my head. A joined-up working example as the basis of a great guide would be invaluable.

4) Tool chain

Remove some of the reliance on an enourmously complex Ruby tool-chain. Building ember-data turned into a day-long slog as I tried to coax a Mac and an Ubuntu box to build it. In the end I resorted to building Ruby itself as nothing else worked. I still can’t get it build on the Mac. At one point I had an error teling me that JRuby was at fault despite it not being installed on either box.

The I have found this week to be especially frustrating is that I can see the great ideas and the sheer power of Ember out there just in front of me but mostly slightly out of reach. I’m continually waiting for the grand moment of enlightenment where it all makes sense and I can just start developing. But I’m, sadly, going round in circles. While a lot of this is my fault — I keep leaping ahead and trying to do things that I haven’t read the docs for yet. But some of it is also the fault of the docs fault themselves as when I try to find an explanation of what (basic) thing I’m trying to do it’s not there.

To end on a positive:

I’m persevering because I am convinced of the potential, despite my frustrations. That in itself must say something important about Ember!

(oh and I’d be very willing to help once I get to a point where I have something other to give than an account of my failures!)

3 Likes

The amount of files I need to touch when I add a new route is driving me nuts … this is a commit I have in progress

I have to touch:

2 * localization files
2 * ember route files
1 * ember view file
2 * ember template files 
1 * rails route file 
1 * rails controller file 
1 * ember controller file 
1 * ember model file 

… sometimes its more … making little changes requires a year of ceremony, this needs to become simpler somehow.

3 Likes

Highly agree with the “mental migration” concept. I come from PHP & Rails MVC background where Views are not the same as what Ember uses them (it’s closer to templates). They key here is to remember that front end MVC frameworks are still relatively new and things needs to be explained as such.

Here are two microdetails whose consideration could improve the getting started experience.

  • While the capitalization of JavaScript identifiers is important in general, and for Ember in particular, Ember’s documentation sometimes styles headlines in all-uppercase (as of 2013-03-25):
    ** {{VIEW}} instead of {{view}}
    ** EMBER.CONTAINERVIEW instead of Ember.ContainerView
    This makes it hard to copy-and-paste names. Also, it can get confusing with all-uppercase identifiers, for example the LOG_BINDINGS property.
  • It may be helpful to load Ember’s library on the API documentation pages. As of 2013-03-25, this doesn’t seem to happen (" Ember; ReferenceError: Ember is not defined ").
    While the API pages don’t need to actually use Ember, providing “direct dev console access” to Ember.X allows to play along with Ember while reading its documentation.
    As a prime example, the jQuery API documentation pages load the jQuery library themselves (e.g. see the documentation for $.getJSON(..) ). jQuery’s API documentation provides sample code. Testing this sample code is as easy as opening the browser’s dev console, copy-and-pasting the sample code there and running it.

On the API pages and the Guides pages, it may be helpful to provide an individual “What can we improve here?” text field (or discussion area) for each individual page.
With this in place, visitors could then provide informal, pragmatic, and unbureaucratic feedback about what they found hard to understand or what they think would help the documentation for each particular page.

I’d like to add that we should actively encourage people who have put out posts and docs to prefix what version of Ember their code applies to and to also encourage them to update their samples.

My first brush with Ember was a very frustrating 3 hour debugging session through minified code to find out that I had been running ember.js-1.0.0-pre through a outdated ember-rails gem while the official documentation was on -rc1 and the tutorial code I was looking at was probably from a version before 1.0

Very annoying to say the least…

1 Like

While I completely agree that the concepts presented in the Ember guides tend to assume that you know what they mean, I think that the “mental migration” is in part (if not predominantly) the responsibility of the adopter.

Granted, more could be done to clarify the terminology and conventions used by Ember, but I think that it is extremely difficult, if not unrealistic, to know/assume where your adopters’ background lies.

It seems to me that a lot of beginners, not just with Ember, don’t take the time to understand the concepts, reasons, pros and cons of what they are doing, before they jump in. This unfortunately leads to misconceptions and assumptions that are based on a lack of knowledge.

I think a great place to start would be to provide a basic overview of what MVC means in a javascript sense. There are already good examples/explanations of these concepts available on the web (for example this post by Addy Osmani), and perhaps a link to something like this would help beginners understand what MVC is and why they need, or dont need, it.

I fully agree with @everwakeful on the idea of helping “mental migration”. However, I would like to specify what we (beginners) need to have as source of information.

As a beginner in Javascript and Ember, I would actually like to better understand what MVC means to ember creators, and what are their mental models. I am not interested about what other javascrit framework creators think about MVC, but I am really interested about what it means in the context of Ember.

I easily imagine that javascript experts are very interested to confront the points of view from various “gurus” and various frameworks, or maybe abstract the architecture and discuss about MVC “in general” and what it should be or not. But again, for a beginner, those discussions and concepts are useless and too complex.

What we (beginners) need to understand is what are the mental models of Ember framework creators, understand them and be able to think like them. Then, we could use their tools with ease and productivity, and later, maybe, be able to provide better alternatives.

A few points to add based on my limited experience so far with Ember.

First, examples of how not to do it are just as valuable as examples of good practice. This forum’s seen many variations on “Does this go in a router or a controller?” and I’d encourage the doc to be forthright about what doesn’t belong in each as well as what does.

Second, be aware that every piece of example code you include, even the simplest few lines, will be considered as canonically the right way of doing it unless you explicitly say otherwise. If you define a set of routes, say, to demonstrate some point and it isn’t how you’d configure routes in a realistic project - maybe you’re not adhering to REST or something - be explicit and say so, within the code example. Don’t assume readers will realise this point: they’ll be too busy cutting and pasting the code to read the surrounding text.

Similarly you should consider the Starter Kit part of the product, and ensure it follows best practice and doesn’t rot.

Finally: what, when, why, how, who. Too much documentation, especially API doc, concentrates on what and how and doesn’t touch on when, why or who.

Thanks for reading.

4 Likes

Lots of good tips here!

If you want to build a step-by-step tutorial, may I suggest Codeacadamy? There are quite a number of API lessons there already, from Parse, SoundCloud, & more.

Okay so I’ve been trying to learn how to Ember for a while now. I consider myself and average programmer, I had no Ruby or SproutCore background, familiar with BackBone, Spine, Knockout. I had a lot of challenges learning Ember, but I think I’ve finally started to get the swing of things…

I like…

  • The philosophy… MVC… separating of concerns, Ember showed me how to truly decouple.
  • Goal, I like it that the framework has a goal, sick ass web apps.
  • Community & Culture… i like the hamster.
  • The guides are pretty sweet… i remember when they first arrived, awesome.
  • The new intro video has been the reason for my ‘level-upping’ of Ember.

My suggestions / wish list (I am still learning Ember)

  • Ember is a full-app framework, so please include full-app examples… (with Ember-Data please) I feel like with Ember what’s proper (at least when you’re new?) is to use everything together… what I learned from the video was, the less I do (don’t instantiate anything) the better…
  • if Ember has a bunch of full example apps on it’s site, it can serve as a central spot of reference for best conventions and best practices… the API changes so much that if you are following a guide elsewhere, it’s hard to tell if it’s outdated…
  • Complete App examples with full Ember-Data examples please…
  • Complete App examples without Ember-Data that does persistent storage please…(though this blog post goes a long way)
  • More naming conventions documentation, this is just cool… my_name get converted to myName … although it’s easy to figure out, a reference point would be sweet, good pattern to follow even if you aren’t using Ember
  • Ember needs “middle docs” … the guides don’t give enough detail, and the API is unwieldy… how bout a middle version of the two that list all the things you can do with the most common classes… i’m talking about Models, Controllers, Views, Templates, Routes…
  • window globals / introspection methods… for the life of me, I can’t find the instantiated app… to poke around… window.app ? how do I console.log window.app.todos.toJSON() ? idk haven’t figured it out
  • ember-data docs please.

Maybe put a real emphasis on to not instantiate stuff… idk once I let Ember do it’s thing, it’s like taking of training wheels… i was trying to do too much before, trying to connect every piece to every other piece manually… I didn’t realize they were already connected… just had to let it go… now we’re cruising.

Lessons Learned:

  • Use EmberData, all of it, espectially the RESTAdapter… don’t try to be a hero and not use EmberData, just use it. (although I have to try what they said in the above mentioned blogpost)
  • Let Ember do all the work… don’t instantiate anything.
  • Stop trying to find and inspect the instantiated objects in the console…

I think the single hardest thing for me to do was hook up Ember & EmberData … everything was good until I came to the Models… (remember my backend is not Rails)

The single longest thing it took me to understand was to just let go and let Ember do it’s magic.

I also want to say Thanks for developing Ember, I’m having a good time learning it, and learning the philosophies of proper MVC… Ember is for ambitious Applications… it is an ambitions Framework :slight_smile:

2 Likes

This one bit me yesterday:

X = Ember.ArrayProxy.extend({content: []}); 
a = X.create(); 
a.pushObject(1); 
b = X.create(); 
b.pushObject(2); 
console.log(b.get("length"));
> 2

Took ages to figure why some very weird stuff was happening.

Yeah this is a pretty well known “issue”, For me @ghempton was the first who explains this well http://codebrief.com/2012/03/eight-ember-dot-js-gotchas-with-workarounds/ chapter 6. It seems it should be somewhere in the doc…

3 Likes

Provide sample applications which will use all the features of ember.

Provide tag lines indicating how each syntax is written and how we can customiize

More examples for the Classes>Methods.

For example in this documentation could be obvious how to use the method forEach… but not for me.

Is it?

Ember.Enumerable.forEach(function(){}, []);

Or is it?

[].forEach(function(){}, target?)