Playing around with Ember this weekend I had a very frustrating time getting it working. Whilst the documentation isn’t bad per se, it is completely devoid of working examples, instead it only has snippets of app and template code.

Since it’s such a new framework there have been significant changes in the last year meaning any tutorials you might find online, even from a few months ago, are out of date and may include no longer functional or no longer recommended practices.

I did manage to find one good screencast by Toran Billups, as I followed along with the tutorial with my own code and got to the point where I needed to define my Model I found that Ember handles this with Ember Data. This isn’t currently part of Ember’s core and isn’t available for download, instead you have to clone the repo and build it using Bundler.

At this point I almost gave up.

For some reason, possibly related the version of Ruby installed on my machine, it simply refused to compile and not being a Ruby guy I didn’t really fancy spending the rest of my evening tracing obscure debug messages in a language I didn’t really understand.

After some food and some thinking I came back to the problem. Rather than trying to compile it myself I figured that someone else must of done this already. Googling around I found a few versions, one of them even on the project’s GitHub download page, but none at the latest version. I went back to Billups’ screencast to just watch the rest without following along when I spotted a link to his GitHub repo of the project.

‘Aha! that should have the code I need’ or so I thought. GitHub was having a ‘Major service outage‘. Great. Fortunately the outage wasn’t so major that I wasn’t able to download the zipped version and extract the elusive library inside. At this point, if it had been a game, it would of been a little bit like this.

Now I can understand that the Ember folks make you jump through the compile hoop because things aren’t stable yet and they don’t want loads of bug tickets for things they already know are broken. But raising the bar too high doesn’t help either, it’s much more helpful to newcomers to have a simple working demo and up to date documentation than a suite of unit tests. I understand that Ember is still new, it’s not even 1.0 yet, but a little help for us newbs would go a long way towards building a stronger community around the project.

It’s worth saying that after all that when I finally got my basic little app working, it worked great and I’m looking forward to doing more with Ember in the future.

Tl;dr: Open source projects: always be newb friendly. You can download Ember-data.js here.