Perspective of someone new to SPAs: Large tutorial in guides is incredibly confusing

[lisaychuang]

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

• a new build tool
• a web framework
• a "data persistence" library
• a testing framework
• a test assertion library
• the concept of a single page application
• "next-generation javascript", including a new "import" syntax I was previously not familiar with
• JSHint

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:

• Promises
• const vs. let
• the idea of using components {{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.

• params vs. hash for handlebars helpers
• QUnit
• the router vs. routes

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:

• Setting up the tests
  • The concept of acceptance tests "verifying that a route is loaded" is mentioned, but I had no idea what a "route" is at this point!
  • The "andThen" helper is introduced before "asynchronous test helpers" are mentioned. I was quite confused as to why I would need to "wait" for anything to complete
  • Although a screenshot was added within the last week, there were references to "the data" and "search field" thrown around, for which I had no context at that point.
  • By and large, because this was so overwhelming to grasp, I just copied/pasted and wasn't able to absorb or understand much.
• Routes and Templates
  • This sentence is supposed to help me understand what's going on, but cannot be understood without any of the concepts being introduced yet 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...
  • "route" and "route handler" seem to be used interchangeably. Are they the same?
  • Use of ember-specific terminology is mysterious for newcomers (i.e., "the generator has mapped a new route for us").
  • Sometimes files are referred to by their name, and sometimes by their path within the project. Particularly when we end up with many files having the same name later on (i.e., index.js), using paths is more helpful.
  • The section on {{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?
  • made even more confusing when I saw the mailto: and tel: <a> tags in the example itself.
  • More jargon like "seeding our rental list page". What's seeding? I'm starting to lose confidence in my ability to make it through the tutorial right about at this point.
  • More references to the "router's mapping" before the router is talked about much. Is there a beginner-friendly way to articulate this?
  • Here we go again, writing tests for code we haven't seen yet. This might be ok if you're already familiar with ember, but building a unit test for a route before knowing what a route is = 👎
  • When we use the replaceWith method in the route, I believe this is the first time I'm being asked to write non-test code.
  • I'm familiar with the JS concept of this, but how do I know what this will be in this route handler?
  • what's _super? Is this private code? This line in general is not even explained this._super(...arguments); What's "...arguments"?
  • Totally puzzled by this 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 🙃?
• The Model Hook
  • The word "template" is being thrown around again. I asked someone and learned that these are my HTML+handlebars files.
  • 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.
  • What's a hook? Is it a function? A special function? Never covered, and possibly more jargon that could be eliminated for the benefit of beginners.
  • While I'm glad to finally be introduced to the ES6 way of defining functions on objects, it's late. This concept has already been used in the previous step in order to define the beforeModel method on a route.
  • Finally the concept of a hook has been defined, but it had already been referenced many times, and I had no idea. Time to re-read this page from the beginning now that I know what this term means.
  • 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"?
  • The part on the {{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?).
• Installing Addons
  • The explanation of how the 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?
  • Another totally new concept: mirage. How does this relate to ember-data? Having reached the end, I have no idea what the difference is between them, where the line is between official ember stuff and community projects, etc... Does everyone use mirage for every project? Why do we need this?
  • 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 about
  • You've asked me to create something called an adapter. What's an adapter? I'm just copying/pasting without understanding any of this.
• Using Ember-Data
  • I followed the part on Models pretty well, until....
  • Now 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 :(
  • This is the last sentence: 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).
• Building a Simple Component
  • Again, writing a test first, when I have no idea how an Ember component works, forces me to move forward without understanding anything until the very end.
  • What's a "stub"?
  • let is used, with no explanation. We used const before. Why?
  • The "component consists of two parts" is great, but comes in the middle of the section. I suggest moving this to the beginning so readers don't have to go through the test stuff while still lacking this simple and well-articulated explanation
  • There's a reference to the term "actions hash". Are object and hash interchangeable?
  • 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.
  • As we start fleshing out the helper, in the explanation the term destructuring, "ES2015" is used. How is this different from "ES6" that was referred to earlier in the tutorial?
  • What is destructuring? This could probably benefit from a small "Usual JavaScript" vs "ES2015 JavaScript" comparison.
• Building a Complex Component
  • This is where the train really starts to come off the rails, and is where I have given up most recently due to confusion and frustration
  • Almost immediately, more jargon is used without explanation 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?
  • A component "calling out to two actions" is also introduced without any explanation as to what "calling out to an action" means. So far we've just used a very simple action to toggle something inside a component
  • In the explanation of the 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.
  • In the section where we write an integration test...
  • we have a line import RSVP from 'rsvp';. What's RSVP? What's RSVP.resolve()?
  • what's 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?
  • Syntax hilighting seems to be screwed up
  • What's this.$?
  • I couldn't find documentation for assert.equal. I eventually found this -- is it the same thing?
  • What's a component contract?
  • Another reference to a component "yielding to" something. Still no explanation as to what this is or how it works - yield the results list to its block
  • What's the difference between <input> and {{input}}?
  • A reference to "typing a pattern" confused me. What's a pattern?
  • 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?
  • The idea of one action calling another action seems very complicated for what we're trying to do. Is there a simpler way?
  • I still have no idea what closure actions are, and how they relate to closures (which I understand) or Ember actions (which I also understand).
  • The concept of a controller is used, without introducing it or explaining its purpose. When might I use a controller, and for what?
  • The switching between building components, to controllers, to tests to mirage and back again is jarring, and I'm left following along without grasping much of why we are doing this stuff. I'm left without understanding how to build a complex component, what makes this component complex, etc...
• Services and Utilities
  • 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?
  • Some concepts of the "registration API" are used without any explanation. What's 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.
• Overall
  • The jumping back and forth between application code and tests may be how experienced developers work, but it's detrimental to the process of learning.
  • In general this tutorial seems to assume a lot of knowledge (not just conceptual, but understanding of jargon). Is all of this knowledge required before people can use ember?

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.

[toddjordan]

Thanks for taking the time to record all of this. We are looking at improving the experience for beginners and this is valuable.

[trek]

@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.

[mike-north]

@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

• Making sure we start with the smallest teachable atom and layer on gradually from there. I've had success in staring with an application template and controller, adding helpers, adding components, etc... eventually adding routes and ember-data, finishing with testing.
• Back out of teaching via TDD. It introduces unnecessary complexity and detracts from the reader's ability to absorb the many new core concepts they have to learn
• Ensure we define terms before using them, use the same terms consistently, and eliminate any technical jargon that doesn't help us reach the goal of teaching this material as simply and effectively as possible
• In places where we decide that it's not appropriate to dive deep into a topic, at least provide links for people to go on a useful tangent (i.e., ES6 language features, the use of things like 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?

[jacefarm]

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.

[locks]

@jacefarm you should tell them that :P

[jacefarm]

@locks Pursuing. They have no road-map for Ember.js. Unfortunate.

[tomdale]

@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.

[tomdale]

@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.

[mike-north]

@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.

[bcardarella]

@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.

[trek]

@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.

[mike-north]

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).

[lisaychuang]

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:

• Learn to build a "Hello World" app with Ember, and then move on to something more meaningful
• Get a basic understanding of the most important parts of Ember (components/handlers/ helpers/ utilities etc)
• Experiment to see if this a tool that feels right for me
• Get excited about Ember! 🔥

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.

• A lot of tools for less-experienced developers use pre-written tests as criteria to PASS for each stage of the project. This helps to sell the value of TDD and test-writing without adding another thing to compete for attention and focus.

I do feel the tutorial can benefit from better organization by:

• Introducing any necessary concept and terminology definitions in advance of using them instead of calling them out mid-page - helping Ember beginners frame the material they are asked to absorb. e.g.
  • What is a component contract
  • What is a model hook
  • What is a stub
• Use simpler language. It's daunting to learn a new framework, keeping in mind for many developers English may be a second language -- programming as their third language -- using simple language, visual analogy, and side-by-side comparison with code snippets to communicate ideas would be helpful!
• Link to Ember documentation (e.g. Controllers) . Yes as a developer I know I should Google/Reddit/Stackoverflow my questions, but if the information is available in Ember doc, can't I just open the link to read it? In some cases I ended up googling and found the wrong information (i.e., assert.equal)
• Progressive, granular learning. Beginners can follow along and build foundational understanding of Ember, while developers more experienced (e.g. with React/Ng2) can move along at faster speed without missing the essentials?
• Differentiate more clearly between add-on / libraries / built-in functionality. For a beginner tutorial, is it really necessary to tackle Ember data + Mirage + RSVP promises + Google map API all in one go? If yes, it would be helpful for beginners to know what's baked into Ember and directed to explore Ember Add-ons in their own projects later.

I hope these feedback are more specific and actionable!

Thank you all again, and I truly appreciate your encouraging feedback!

[toddjordan]

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.

[pixelhandler]

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…

1. an intro that shows how to create an app put some stuff on screen, a walkthrough of basic concepts (some spoon feeding);
2. then, layering in tests for work already setup, perhaps a couple acceptance (functional) tests. Maybe an example of "test first" for an integration (component) test (but only after some components were already build in the tutorial).

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.)

[pixelhandler]

@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.

[optikalefx]

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.

[ghost]

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.

[toddjordan]

Actionable Tasks

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.

Include links to javascript/es6 concepts when first encountered

• [x] Promises
• [x] const vs let
• [x] this (as within an Ember Object)
• [x] this._super
• [x] destructuring

Acceptance Testing

• [x] Introduce/Explain/Link QUnit and QUnit Asserts
• [x] Route mentioned before introduced
• [x] Need for andThen helper not explained
• [x] Mention of "data" and "search field", but not clear what it applied to (clarify)

Routes and Templates

• [x] Explain/link to what the "router" and a "template" is before diving into it
• [x] Use consistent terminology between "route" and "route handler"
• [x] "The generator has mapped a new route for us" - confusing language for newbie
• [x] Change any file identified named by just name to use entire path
• [x] Explain the need for the {{link-to}} helper as opposed to just an anchor tag
• [x] The word "seed" might be confusing for some when describing initially loading content on the page.
• [x] {{outlet}} explanation is not clear, especially since route/router hasn't been explained.

Model Hook

• [x] Text mentions add, update, and deletion of rentals but not in the current scope of the tutorial
• [x] Explanation of a "hook" is given after it has already been referenced several times
• [x] The text "The model hook returns our rentals array and passes it to our rentals template as the model property" is unclear
• [x] The terms "model data", "model property", "model", and "model object" seem to be used interchangably. Use consistent terminology.

Installing Addons

• [x] Remove the "how it works" part of the intro to ember-cli-tutorial-style, Explain more why we are including it.
• [x] Explain why we need ember-cli-mirage, and how its different than ember-data
• [x] Text mentions a GET request, when in reality that request is never made
• [x] Ember Data Adapter concept is introduced with no explanation

Ember-Data

• [x] Expand on "Now we have a model in our ember data store". What is a data store, and how does a model get there?
• [x] Mentions sending GET request but no GET happens (mirage)
• [x] Need a link or explanation of providing a back end to the application, and why this would only be in production (wouldn't necessarily).

Building a Simple Component

• [x] Explain/link what is a stub
• [x] Move explanation of a component to the beginning of the section
• [x] Explain what "actions hash" is
• [x] Explain or clarify what "default template helper" is

Creating a Handlebars Helper

• [x] Introduce/explain/link handlebar helper params (differences in types)

Building a Complex Component

• [x] Introduce/explain/link the concept of yielding as it applies to block components
• [x] Introduce/explain/link Closure Actions
• [x] Expand on what a component contract is (possibly when components are introduced in the simple component page)
• [x] Use in the filter example as opposed to {{input}} helper. Give explanation to what is going on there.
• [x] Explain "Binding" or use a better term in the context of the input tag using the action helper to call an action on its parent.
• [x] Introduce what a controller is and why we are using it.
• [x] Do a better job explaining the different parts of the component and what their purpose is.
• [x] Explain why this component is considered "complex"

Services and Utilities

• [x] Explain "implicit function"
• [x] Introduce/Explain/link this.register in test
• [x] Introduce/Explain/link service injection

[ghost]

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.

[toddjordan]

@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!

[toddjordan]

Update:

• Added changes to clarify sections around routing and model hook.
• Delayed the introduction of Ember data until later on in the tutorial, so that the concepts wouldn't get confused with the more general concept of the model hook. (will likely be more changes in ember data later). Next PR will be moving the mirage introduction back as well.
• Currently also working on some refactoring around introducing test concepts to be friendlier to newer users.

[locks]

@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.

[dgeb]

@mpash I should also add that your statement was neither empathetic nor respectful, two goals of our community guidelines.

[ghost]

@dgeb nifty 👍

[RyanNerd]

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.

[toddjordan]

@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.

[ghost]

@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.

• It's okay to demand something from the community.
• It's okay to remind the core team nothing has been done.
• It's okay for me to say that it needs to be a focus before anything else.

Documentation is your framework's first impression to a user. You have to market it just like you would a physical product.

[locks]

You know what happens when you light something on fire? It burns out.

[ghost]

It was a jocular term related to Ember, but thanks for your quick quib. It's time to warm up that frozen heart.

[ghost]

@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".

[ghost]

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!

[bcardarella]

Can we lock this thread?

[ghost]

@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.

[mmun]

Please everyone take a little time to cool off. We're all in this together!

[locks]

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 :)

[toddjordan]

Remaining checklist items have either been addressed or opened as smaller issues. Ready to close.

[acorncom]

Sounds good, closing it now