Closed lisaychuang closed 7 years ago
Thanks for taking the time to record all of this. We are looking at improving the experience for beginners and this is valuable.
@lisaychuang Thanks so much for taking the time to do this!
It would be super helpful for us to know the order you went through the guides in general. This feedback mirrors a ton of feedback we've gotten in the past, and is the basis for the current Getting Started where we cover – briefly, based on past feedback that people want just the basic info to get started – some of the prerequisite concepts for getting your feet wet in bunch of (probably) new concepts.
Did that guide not help? Did we not do enough to draw attention to it?
As a side note: the jump from just jQuery to any of the "modern" web frameworks is huge leap. They all have their beginnings in circa 2010 (or earlier), all "grew up" during a period where JavaScript and browser technologies were changing at an incredibly rapid pace compared to 2005-2010 where they were fairly static.
And, strangely, there aren't many technologies that live in between jQuery and something like Ember, React, Angular, etc in terms of concepts you need to know.
This isn't mean to discourage: be ready and eager to tackle many new topics and concepts.
@trek I believe only about 25% of this has to do with the leap between jQuery and something like React (i.e., use of const
, let
, destructured assignment, etc...).
There's a HUGE amount of this that could be addressed, and would benefit broad swaths of learners and users, including
RSVP.resolve
, QUnit assertions, etc...)To be clear, I'm eager to give this some attention (urgently needed). This is just one representative example of dozens if not hundreds of beginners that have shared similar feedback with me when I teach workshops and video courses.
Ember has the potential to be the best UI tool for the job for less-experienced programmers -- essentially "good architecture in a box". Is there a good reason why we shouldn't aim for that in the newcomer-oriented guides?
I'd love to see an Ember course created at CodeAcademy. Their curriculum approach is granular, repetitive, cumulative, hands-on, immediately clarifying, rewarding, and would benefit the Ember community. Their courses are wonderful entry-points for beginners and the experienced alike.
@jacefarm you should tell them that :P
@locks Pursuing. They have no road-map for Ember.js. Unfortunate.
@lisaychuang Wow, this kind of detailed feedback is rare and incredibly valuable. Once someone has learned the framework, even a little bit, they are fundamentally unable to see it through the eyes of the beginner. Thank you so much for taking the (what looks like it was significant) time to write this all down.
@mike-north Great points there, but there's one thing you assert that is not clear to me:
Back out of teaching and encouraging TDD at the same time. It introduces unnecessary complexity and detracts from the reader's ability to absorb the many new core concepts they have to learn
I'm not a TDD zealot by any means, but done right, I think teaching testing can be a very valuable aide in helping people validate their understanding. It's very possible we are not taking the right approach, or testing in Ember is too complex at the moment. But I want to make sure we don't throw the baby out with the bathwater.
@tomdale I'm definitely not advocating that we abstain from teaching testing -- only that teaching "by test first" is needlessly confusing. It's one thing to write integration tests in advance of building a component if you have built dozens or hundreds of components before, and quite another to write your first component integration test before you've even built your first or second one.
@tomdale consider how much is being asked to absorb at once. Introducing Ember's concepts and the the concepts of TDD as well as the testing API is a lot for someone that has no prior experience. The most important thing is for a beginner to get to something useable as quickly a possible. This is what will hook them, not the testing.
The other way to look at this: in order to TDD properly you must understand, at least in part, the system that is being tested. When a beginner is being asked to TDD something they don't yet know anything about it can feel daunting if not impossible.
@tomdale @bcardarella etc: I think it's easy to focus on things like "what order the guides are read" or "is TDD is a good thing to start with" or and lose sight of main issue that @lisaychuang raised that we should address first: the guides have lost a bit of overall cohesion over time.
As each person updates a particular unit, we haven't kept good track of the integration. As a result, you can probably can't find much that is false in the guides, but the guides taken as a whole can be (as we've seen) confusing because the individual pieces no longer fit together quite right.
There's been some talk in #-team-learning
on Slack of a new tutorial/different guide order etc. All of this is good, but secondary to the immediate actionable issues that topics are used before they've been introduced.
Before we make large structural change, someone should tackle these.
The most important thing is for a beginner to get to something useable as quickly a possible. This is what will hook them, not the testing
This mirrors nearly 100% of the feedback I've received. Too much to grasp, way too early on. People don't even get a chance to get excited before we test their patience and resolve (via copying/pasting test code, giving us the benefit of the doubt that they'll start to understand what they're doing later).
Hi everyone, Thank you all for your kind feedback, I really appreciate the level of discussion on Twitter and here on Github! It took time for me to comb through the tutorial, going back over it page-by-page and documenting my thoughts, and I am happy this helped to surface issues from the perspective as someone new to Ember.
As a beginner to single page apps exploring Ember as a framework, the tutorial was overwhelming and introducing multiple concepts simultaneously (routing / components / handlebars / ember-data / ember-cli / mirage / qunit / TDD ) further confused me. It's like leaving the house with light rain, only to be hit in the face by a tropical rainstorm. ⛈ 🌪
My goal of going through the tutorial was:
Instead, I find myself confused and frustrated at the end of the tutorial. 😥
To both @tomdale @bcardarella points on TDD, I appreciate the value of a test-driven approach to development, but if the goal of a tutorial/guide is to introduce beginners to the framework -- it may be more beneficial to introduce tests mid-tutorial AFTER the learner is more comfortable with concepts being tested. Tests may be better positioned as "points to consider" highlighting Ember nuances / areas to address.
I do feel the tutorial can benefit from better organization by:
assert.equal
)I hope these feedback are more specific and actionable!
Thank you all again, and I truly appreciate your encouraging feedback!
A lot of valuable input to work with here. Our next step is to sort through this and create a list of specific, actionable tasks out of this feedback. We'll be working on this over the next week or two and will post updates to the issue.
This is super interesting! Thanks for posting this!
I just went through the first few pages of the tutorial. I have to say it's a turn off to start with 5-6 acceptance test for concepts that are brand new and specific to the framework. My expectation is that I can see something working quickly (in my browser). A flow like the workshop experience would be ideal in my opinion, see: https://github.com/emberjs/guides/issues/1695#issuecomment-253698828
(Disclaimer: I've developed with Ember for almost 4 years now; I recently took a read of the React and Vue tutorials, and have went through the Elm tutorial as well.)
My hope is that the Ember tutorial can do the job of an Ember Tech Evangelist. From my experience at Ember meetups, one example that blew me away was when… a Firebase tech evangelist setup a demo and example repo and showed off Ember + Firebase. It was super engaging and drew people in to learning more about Ember.
The current tutorial, leading heavily with tests first, is not what I consider the experience that will engage and draw developers into learning more, or even lead them to want to finish the tutorial. Introducing testing first seems to defer gratification of seeing new technology work first hand. There are always exceptions. I love tests, so quickly I begin to think, "How do the tests work?" But first, I think, "How does this tech work, and what does it look like, in action?"
I recently helped a rails developer, new to Ember, with the tutorial. I found myself explaining why the tests work the way they do. That conversation should have happened after a few moments of… "Wow, this framework is sleek and snappy, I like it… So, tell me about testing".
I think the tutorial needs two parts…
Testing should be introduced after the developer has a feel for holding the steering wheel of Ember and the CLI tools. Conceptually speaking, The pace of the tutorial should be to crawl, walk, then run.
Perhaps I missed it, was there a prerequisite to the tutorial, perhaps an video on the basics of Ember.js? I see the "Core Concepts" link under getting started. My expecation is that the tutorial would in a sense illustrate the core concepts. But instead leads with more "Testing concepts".
I know a lot of person hours went into the super rentals tutorial, the demo app can be visited online as well. My hope is that the tutorial can take this feedback and grow in such a way it can increase it's ability to draw developers into "catching" Ember core concepts and Ember testing by "doing". My hope is that the community can find a way to ease in core concepts while also providing some immediate/working feedback that engages the developer to learn more about Ember during each step throughout the tutorial.
On a similar note… The challenge is that a lot of consultants do this type of "training" for profit, while the learning team is mostly doing this for free. I think that there is room to bridge those two motivations. For example, for those interested in providing training as a service, maybe the requirement for a paid training session is to complete the tutorial. It would be great if the tutorial was done so well, that it created anticipation for a more advanced training session. Also if the tutorial was improved per this feedback I think there would be a wider audience of developers seeking to learn more. (I dunno maybe a kickstarter to find cash to fund paid work for the next iteration of the tutorial.)
@toddjordan the most recent new "tutorial" experience I've had was… completing the Elm tutorial.
What I liked about that experience was that there were a few small steps first, simple use cases also at the end of certain sections, a challenge was given regarding what I should complete in order to learn the concepts more completely, by dev'g on my own.
During my first pass through the Elm tutorial I skipped those challenges; however that lead to me returning to the tutorial and completing the challenges. I needed to own the learning experience; if I was to reap the entire benefit of the tutorial, as it was designed.
I find that it's easy to copy and paste during a tutorial. It's a great learning experience when there is also a challenge - to go deeper and discover something. Accepting the challenge (homework, if you will) helped me to realize that there were concepts that would take additional time and effort, on my part, in order for me to gain a strong grasp of a new language. Ember is not a language, but as pointed out from this perspective - the learning curve is perhaps just as steep.
I guess I'll give some input on how I used the guides, to offer some perspective. It's hard to create a guide for experienced JS devs and beginners at the same time. I've been involved in JS for 12 years. If the guides are too basic, I start to skip through things. Which is exactly what I did when I first went through the guides to learn Ember. I just brushed through them very quickly.
I missed a lot of things. The guides have been a great resource though, to dive deep into a concept that I now need to learn more. For example, I didn't need initializers until my 2nd ember app. I thought they were great to jump to, and read more in depth about that concept.
My point is, I wonder if there needs to be a stop gap. We have the getting started, the guides and the reference. Maybe there should be a 4th concept -> for beginners, and then we have 4 distinct learning sections.
1) Getting started. This is for those just taking a peek.
2) The guides for beginners. This goes through things slowly, defining ES6 terms, not using TDD, building a simple app. Still hitting most of the talking points, but it's written in a much more explanatory way.
3) Ember concept definitions (the current guides). The place I can go to read more in depth about things like the router, initializers, link-to & dynamic segments. The hidden gems.
4) The reference, all of the API methods for objects like we have now.
Just my 2 cents.
I agree with @optikalefx, there is a lot in Ember that only really clicks once you need it. Most of those areas aren't that complicated in isolation but you can feel buried by them when they are all thrown at you in quick succession.
I think more could be done to make it clear that Ember probably isn't a good place to start unless you are at least a little bit comfortable with vanilla JS. That doesn't mean telling people to go away and never come back but could involve pointing them towards a set of useful resources that they can work through first.
I found the Ember CLI 101 book much more useful than the official guides because it introduced things in context and I had to write code rather than just trusting that the code I was shown would work. Obviously it is not a 30 minute quick start but the nature of Ember means that (unlike React) it's hard to see the real value unless you spend more time with it.
One area where I think Ember really shines is the developer experience, largely because Ember CLI is awesome and a lot of logical decisions are already made. It's hard to convey that in guides/tutorials but for me it is one of the strongest stories Ember has to tell.
On a separate note, I'd be happy to offer some time to help review and/or even try writing/recording some guides. I've taken a fair amount out of Ember so would like to put something back in.
Based on the feedback in this issue writeup, I've created the following actionable tasks. There are some larger issues alluded to that aren't yet decided on what the best approach would be, around the use of Ember Mirage (tracked in #1695) and the use of TDD (tracked in #1718). We will have some additional discussion and research and will update/create issues as these happen.
I'm coming to this issue thread as a beginner to both ES6 and EmberJS, but I'm an experienced developer with Laravel. When it came to learning Ember for my job, the docs are incredibly dry and lack any formal introduction to concepts it glosses over. More often than not I'm forced to reach out to the API documentation where I'm left to my own devices to decipher what I'm trying to accomplish, not even knowing what I'm looking for. I can tell that documentation is not a focus for the EmberJS team, and given that this issue has been open since October means that they are in no hurry to make it any more understandable, which is just really a shame.
@mpash Hi! There are 44 immediately actionable items listed above. I appreciate your passion around documentation and would love to start working with folks to start getting easy wins on making the tutorial better. Submit a PR if you have any favorites from above and I would love to work with you to get it in. Please remember we are community-driven open source software and rely on contributions from developers such as yourself. Thanks!
Update:
@mpash I would like to remind you that the learning team that was formed to deal with documentation and related issues is entirely voluntary, everyone is trying their best with the available time they have. If your goal is to incentivise the team to prioritise this item over our numerous other tasks, this kind of disparaging remark is not the best way to achieve that. Vue is a great project and is well maintained by @yyx990803, you'd do much worse than picking it.
@mpash I should also add that your statement was neither empathetic nor respectful, two goals of our community guidelines.
@dgeb nifty 👍
Please move the Actionable Tasks to a project with milestones. Where I work milestones (with expected task completion dates) helps immensely.
Although I don't agree with @mpash negative approach -- he does have a point. The perception is that documentation/tutorials do not appear to be a priority. To be fair many frameworks docs are awful (I come from an Angular background and the first thing my mentors told me was to ignore the official documentation for Angular because it is so bad). Even so this is no excuse for Ember.
@RyanNerd Thanks for your willingness to help! A bunch of these are to be fixed by https://github.com/emberjs/guides/pull/1818. For the rest I will follow your suggestion on once that pr is merged. If you want to help right away, going through the tutorial with that PR and looking for errors would be super helpful.
@RyanNerd It's not easy for me to be nice instead of critical when Ember has everything it needs to succeed. I'm sorry I was negative, but I want to light a fire (🔥) under your butts. You can't get things done when everything is sunshine and rainbows.
Documentation is your framework's first impression to a user. You have to market it just like you would a physical product.
You know what happens when you light something on fire? It burns out.
It was a jocular term related to Ember, but thanks for your quick quib. It's time to warm up that frozen heart.
@dgeb
@mpash I should also add that your statement was neither empathetic nor respectful, two goals of our community guidelines.
It was both, empathetic and respectful. It shows a huge amount of empathy and respect for the users which get disappointed, when hitting on such documentation.
Difficult concepts for those on the "Throne of the Core".
Seeing the further comments re documentation issues, I realize that there is no hope that Ember will get decent documentation.
To all of you, just look a this:
http://aurelia.io/hub.html#/doc/persona/developer
-
@lisaychuang , its very gentle from you to express things so calmly. But then, possibly just one sentence with a few 'forbidden' words would have done better work in making those folks realize that they have failed, and that they have to overwork the tutorial (if not documentation) completely. This affects the doc-infrastructure, which is just ridiculous complicated.
@mpash & @mike-north , possibly the only 2 ways to achieve something with the docs is to produce a tutorial with your requirements. Thus they can see, and compare.
I've started this, as a part of the evaluation (lazaridis-com/js-eval#7), but decided to abort, as the overall effort is far too high.
Finally, do yourselves a favor, and look how many stuff you write about documentation, instead of just picking the right persons to actually specify and write it.
Like an drug-addict has to admit his problem to get help, the "Masters of the Cores" need to admit their failure, too, otherwise there is no help.
Me out here.
Have fun!
Can we lock this thread?
@rwjblue (Ember Core Team, LinkedIn), within #1853
Hehe, yes. The answer in general to these types of Q/A things is to read the docs. That's what they are for! 😁
Note to reader: totally hopeless project.
Please everyone take a little time to cool off. We're all in this together!
We can.
I would like to thank everyone that constructively participated in the conversation and helped us (Todd ;P) open up the tutorial to a wider range of people, especially Lisa and Mike for taking the time and effort to write detailed feedback.
We have additional items on the roadmap to keep improving things after Todd's latest round of changes, such as adding a better introduction to the tutorial to contextualize who the target audience is, as well as possibly moving it to a tutorial-specific section of the website.
I hope the people involved felt their voice heard, sometimes the many hours of volunteering aren't apparent, but we certainly do care or we wouldn't have formed the learning team.
See y'all in other issues :)
Remaining checklist items have either been addressed or opened as smaller issues. Ready to close.
Sounds good, closing it now
My background I have some basic programming background but have never used a SPA framework before. The idea of using something like Ember is appealing because I don't have the experience to make all of the stack/architecture decisions myself.
Going through the guides
The number of new concepts introduced in very early steps (i.e., as early as steps 1 and 2) were totally overwhelming. After speaking with people who know ember, I understand now that I was asked to grasp the concepts of
Even later, there are concepts that were introduced with no explanation. Again, after asking people who have more experience, I now understand that these are:
{{like-this}}
or{{#like-this}} {{/like-this}}
And through the tutorial I also was left with a lack of understanding on certain things that seemed important to me. I expect that I could have looked at other documents to figure this stuff out, but it seems like the guides would benefit from including links / references to explanation right there.
Finally, there doesn't seem to be a well thought out order/ organization of how the topics are introduced. Here's my detailed feedback on a per-page basis, so the experts who maintain this material can understand a beginner's perspective:
Let's start by building our "about" page. Remember, when the URL path /about is loaded, the router will map the URL to the route handler of the same name, about.js. The route handler then loads a template
. I still have no idea what a template is, and have to infer what a route and router might be...index.js
), using paths is more helpful.{{link-to}}
was quite confusing until just about the last sentence. I'm used to using<a href=
-- why can't I use them with ember?mailto:
andtel:
<a>
tags in the example itself.replaceWith
method in the route, I believe this is the first time I'm being asked to write non-test code.this
, but how do I know whatthis
will be in this route handler?_super
? Is this private code? This line in general is not even explainedthis._super(...arguments);
What's "...arguments"?The {{outlet}} defers to the router, which will render in its place the markup for the current route, meaning the different routes we develop for our application will get rendered there.
What's deferred to the router? What's the current route? What's the router? Who am I and what I am doing 🙃?We know that rentals will not be static, since eventually users will be able to add, update, and delete them
. Having finally slogged to the end of the guides after giving up three times, I know that this doesn't end up being true of the final example.beforeModel
method on a route.The model hook returns our rentals array and passes it to our rentals template as the model property.
I understand that the hook returns an array, but what's this about passing something to a template and a "model property"?{{each}}
helper could stand to have the language tightened up a bit. Terms like "model data", "model property", "model" and "model object" are used (interchangeably?).ember-cli-tutorial-style
addon is quite dense, and it turns out that I don't need to know any of this in order to complete the tutorial. I never end up touching any CSS. What is the thing that you're trying to teach me here?This configures Mirage so that whenever Ember Data makes a GET request to /api/rentals, Mirage will return this JavaScript object as JSON
. I learned about how to inspect HTTP requests using the network tab in Chrome developer tools. I don't see this GET request you're talking aboutNow we have a model in our Ember Data store.
What's an Ember data store? How did our model end up there?Ember Data will make a GET request to /rentals
- I still see no get request in my chrome dev tools at this point :(When we deploy our app to a production server, we will need to provide a backend for Ember Data to communicate with
. I would really like to know how to provide a back end for my web application. How do I use it only in production? This raises more questions, and provides no answers (nor are they provided at any point down the road in the tutorial).let
is used, with no explanation. We usedconst
before. Why?Instead, our default template helper is returning back our rental.type values.
- What's a "default template helper"? Seems to mean the thing we just created, but not 100% clear.The filter component should yield a list of filtered items to whatever is rendered inside of it
-- What's this concept of a component "yielding" to something else?wait
test helper, it mentions that Ember will wait for all promises to finish. There's no explanation of what a promise is, or a link to where I could read about it.import RSVP from 'rsvp';
. What's RSVP? What'sRSVP.resolve()
?this.on()
? I tried to google this, but didn't know if it was an Ember thing, a jQuery thing, a JavaScript or ES2015 thing?this.$
?assert.equal
. I eventually found this -- is it the same thing?yield the results list to its block
<input>
and{{input}}
?The value property of the input will be bound to the value property in our component. The key-up property will be bound to the handleFilterEntry action.
What does this term "bound" mean?A stub stands in place of the real object in your application and simulates its behavior.
FINALLY the first explanation of what a "stub" is!In the beforeEach function that runs before each test, we use the implicit function this.register to register our stub service in place of the maps service
- What's an implicit function?this.register
?The call to the function this.inject.service injects the service we just registered into the context of the tests, so each test may access it through this.get('mapsService'). In the example we assert that calledWithLocation in our stub is set to the location we passed to the component.
I can't grasp anything after this point. I GIVE UP.Thank you for taking the time to read this feedback, I appreciate the work that's been done on the guides & tutorials -- and really hope this serve to improve the learning experience for beginners.