We’ve heard you loud and clear that we need to do a better job making it easier to get started with Ember. Specific plans include:
We’re actively working on a Getting Started Guide with live examples that walks the user through building a new application from scratch
We’re writing the script for a short screencast introducing the framework and illustrating how it works that will be prominently displayed on the homepage.
We’re continuing to improve our guides to talk through areas, like the naming conventions we use in Ember, that might be confusing for new developers.
The Starter Kit will return, giving developers a one-click way to try out Ember. (We removed it temporarily to bring it up to date with the most recent idioms, but it will be coming back very soon. This was a hard decision that sucked, but leaving around an out of date starter kit seemed worse than removing it.)
Here’s what we’d like to hear from you:
How can existing documentation be improved?
Other than what we’ve listed above, what more can we do to smooth the on-ramp?
What work would you be willing to volunteer to help us achieve those goals?
Thank you guys so much for being part of the Ember community. I look forward to getting your assistance building the best possible developer tools for the web.
Okay, shamelessly two of those are mine but I still think people might want actual apps to poke around in
Maybe also a list of external tutorials such as the PeepCode, Railscasts, etc. I know linkrot is a problem, but AFAIK there’s no central directory of ember tutorials right now.
Documentation should explain, what are the operation which can be performed within Route, Controller, Model, View. Lots of confusion around should I use Route or controller or view to handle events.
At least 3-4 example applications which cover from Basic to Advance features. Something on my mind:
First Application should be a simple ramp off
Second dive into nested routes or nested model
Third many view in single page and how they communicate with each other
Fourth , how to build reusable components/plugin for others to use. Like Authenticator, Form generator…
I can volunteer to go through the materials which are under construction and provide my feedback.
We need more working samples. The first touch is really important and causes the most frustration.
I converted a full fledged Django app into an Ember app in about 2 hours on a Friday night and it was super fun because I knew what I was doing. But I also tried to create an Ember app from scratch as a live demo and completely failed at it.
A couple weeks ago I put up a website to curate common mixins/plugins like Addepar’s Ember-table or Dockyard’s EasyForm. We could build a library of working samples like that? I think samples should include little apps that can be built in an hour. If I can build it in about an hour from scratch, someone looking at the code should be able to reproduce in 20 minutes. I know that small apps like these don’t demonstrate Ember’s full power, but that can come later.
I’m terrible at coming up with ideas for sample code, so if anyone has any suggestions, please let me know and I will attempt to build it.
I would like to write use-case guides for Ember. I am the co-founder of a startup using Ember as our core front-end technology and I think we have devoted an unusual amount of time to learning its mechanics for use in…less than conventional ways.
I have attempted to cut my teeth on these types of guides by writing blog posts that are entirely encapsulated in jsfiddles over at my blog http://stevekane.github.com . I have some ideas to improve the format but in general I think this style of guide is usually where I learn the most.
We need to do a better job of driving home the message that Ember is, truly, as set of composable primitives and some underlying plumbing for making them interact efficiently. It is NOT a scaffold on which you can expect to write very little code in order to build anything real. People are conceptually tripped up by their mis-guided conclusion that Ember is akin to SproutCore or Cappucino (large UI element-laden libraries).
Trek’s talk at Embercamp was fucking fantastic for illustrating the core concept that UI widgets/elements should often be hand-rolled and that Ember’s objective is to provide you the composable pieces from which you can construct your own complex behavior. Furthermore, he goes on to illustrate (effectively) how you can build ever-more-complex UI elements out of well-constructed smaller elements. We have used this approach ourselves to construct several widgets and we see this as the undeniable future.
This ethos NEEDS to be codified and supported by rich examples in order for people to grok the paradigm shift. Ember.js is aimed at facilitating complex application design using tried and true application architectures and design patterns. In my assessment, this is a powerful departure for many front-end developers from the widget mashup architecture they have long leaned on.
Those of us that are Ember fans owe it to the community to avoid pontificating about the virtues of the Ember primitives and to instead focus on example-based instructions that illuminate their power. When you build a reasonably complex Ember system a lot of the real power of the Ember architecture starts to shine through but it only works when people stop trying to stick balls of playdough together haphazardly and instead select the legos they need from the bucket and carefully design their castle. Ember has a lot of clutch legos, people just don’t know what to do with them.
I think it would be interesting to see a ‘Stages of Ember’ type document with links to SO questions that address the common problems that people have come across and the solutions. For example,
Getting Hello World Running
jquery not defined / include jquery first
handlebars not defined / include handlebars after jquery and before ember
Responding to clicks
‘nothing handled that action’ message / add an event handler on your controller, try it on the route
And so on. Because it’s from the developer’s perspective at the point the encountered the problem it might make it easier to navigate to a documented solution.
I also think a quick guide on how to get started with JSBin to construct learning examples for new beginners would be super useful.
Do you plan to add a Demo section to the site eventually? I have a proposal.
It appears that currently there isn’t enough core dev power to deal with code and docs, and demos, etc. So I thought it would be helpful if the the devs pointed out specific features they’d like to demo and the community would then be able to help them out.
For example, a dev says “we’d like to have an app like this <… some description here …>, here are specific Ember features that can be used to make it <… list of features that are doc- or code-searchable …>”. Then anyone from the community will be able to try and implement one of the proposed demos and in this way learn Ember by doing and helping other beginners in the process.
The core devs may need to review the suggested demo’s code in the end to deem it helpful for learning purposes, but it should certainly be easier for them to do than to come up with demos themselves (their time spent on Ember itself is more valuable). What do you guys think?
I’m speaking for myself here, of course, but I’m sure there are other enthusiasts who are willing to help in this way. I just need pointers that will let me know what to look for in the code of Ember or existing apps. Having a list of such pointers with a brief explanation from the devs will prove very helpful in my opinion.
P.S. I also totally support @hashg’s idea about egghead.io, but this kind of thing has to be done by a core dev or someone already knowledgable in all the hidden ways of Ember.
Maybe we should just make these error messages even clearer. For example, the Handlebars assert could provide instructions on where to get the file and where to put the <script> tag.
As for API documentation, I’m hoping to see more of Ember-Data API in the future. The guide as is, is great and you guys done it very well, but some points which were already raised elsewhere (as in “I don’t understand Ember” blog posts/rants out there) like dependencies and all things to get started should be addressed as soon as possible. I would like to say the topics that address “getting started” scenarios should be very, very, very detailed, to the point of explaining things that most people would consider obvious.
You can call me n00b and that’s fine, but I really like Code School’s approach on interactive tutorials; something along those lines would be really good.
Just to put in perpective, the ASP.NET website has a community area with articles and blog posts from the ASP.NET team and from community. Perhaps Ember could have a sort of “community spotlight” as well, or even better: Integrate the Ember Watch into Ember website and let people contribute with articles.
Another thing that I think would be helpful: allow comments/contributions to the guides and API (will require moderation). And perhaps one of those “was this topic helpful?” type of thing too.
Another things that sometimes bites people is the wrong notion that Ember is “for Rails” only when it’s totally not the case. It should be clear (I know it is, but… ) that Ember is backend agnostic, and perhaps it should be “louder” in the guides/docs/website. Perhaps talking to influent people on different development communities to help creating starter kits aiming “XYZ” backend would be good too.
As for volunteering, I’d love to be more involved with the community and help in anyway I can. I was thinking of translating docs to Brazilian Portuguese, but I’m not sure how much helpful this would be at this point (not that it’s super important since the Internet speaks English anyway). I would also like to reproduce the exact same sample apps you guys are baking but in a different backend, like .NET which is my background. I’m up for whatever if that means helping.
I’ve spent a year struggling with Ember but stuck with it, convinced I must be stupid. I’ve gone through all the videos, I even ported the Peepcode sources into a RequireJS format, but I still feel like a mushroom.
The fact that Ember generates so much code for us is amazing, but I would like to see all the code typed out in longhand first - so we can see what it means to take it away and be autogenerated. If we want to learn how the magic works… I think we need to see all the parts of the trick. The full code would help us see how it all fits together.
It would be good to do a pass and make any exceptions raised as informative as possible about what the corrective action to take in code would be. Noted…
I would like to see more detailed documentation on Ember Data. I understand that it is not 1.0 yet, but better documentation would be appreciated, especially on how and when objects transition into different states.
Best practices guides would be helpful as well. What should go into routes? What should go into controllers? Guidelines or conventions on this would be very helpful.
Maybe these are not strictly helpful to get started, but there is a dearth of reading material anywhere for some of the hidden gems in Ember. Say, things like:
Another thing I found difficult in the current guides on the site is that jargons/concepts are used/dropped-in before they are introduced. Or in other words, I cannot read them in a specific order (from Concepts, to Application, to Routing to Templates etc.), without having to look ahead and understand what exactly is the class.reopen that is mentioned here.
And my two cents on how crowd-sourced help can be effectively solicited for all of these documentation effort could be, by making use of GitHub issue tracker more aggressively. Smaller, atomic, completable tasks could be tracked as separate issues/action items on the Issue Tracker, so that folks could come in and chip away at things there.
One of my friends said the same thing. Initially, I agreed. But I actually think this could do more harm than good. It’d force you to be exposed to a lot of parts of Ember at once, rather than learning new concepts stepwise.
I am, however, in favor of a concise and direct explanation of how, where, and when Ember creates anonymous objects for you. Prolly a short page’s worth of information in the “Concepts” section or in an appropriate appendix.
