Crisis in documentation

#1

I’m not sure if you ember veterans can tell, but the current state of documentation makes the learning curve of ember almost a vertical line, and with multiple alternative out there, that isn’t a good thing.

So on the front page, you see a marquee to get you started

npm install -g ember-cli
ember new my-app

Congratulations new user, you have just broken every single ember.js book, and almost every ember tutorial on the internet. And the official guides are now just wrong enough to make you pull your hair out.

ember-cli does look like a great improvement, but I wouldn’t promote it to all new users until the official guides have been updated, and there’s a solid, easy to understand migration guide so users can still read the current books (that came out last year!)

#2

It’s worth noting that very little of substance from the 1.0 books is irrelevant, and nothing from those books won’t work. You can still download from the builds page and write a text file with a million script tags. If anybody is showing up fresh we want to point them to the modern stuff, but all the old stuff works just fine.

As @trek has been fond of pointing out lately, people who are spooked away by a couple CLI commands won’t be able to find much comfort in any framework pretty soon. JavaScript is growing up. Folks can come along or not, but I don’t think the train is stopping.

#3

Its not that the substance is irrelevant, its too different for somebody getting started. The learning process slows to a crawl. Every example becomes a puzzle and you don’t quite know what the pieces are.

#4

@trek @kylecoberly @kswope, I think part of problem here is that all the major frameworks are punting a little bit on explaining to new / old school devs how to convert to a built and transpiled ecosystem. I also think Ember reached this point in it’s ecosystem first, but if React weren’t so bleeding edge it’d probably be feeling this same pain right now.

While it’s true that explaining topics such as installing node, using npm, and how build tools work and function isn’t Ember’s duty, if every framework decides that, then the workflow upgrade process is going to be more painful than it needs to be.

I started making some small improvements to the installation guides for ember-cli.com to clarify the installation of PhantomJS and Watchman, and as time permits in the next few weeks I intend to write a new “installation guide” that can be used by anyone brand new to these steps. This doesn’t make the pain of learning new processes go away, but at least it would make figuring out where to start a tiny bit simpler.

#5

But you can still do everything the way the books say. For that matter, you can use JSBin or something to get started. Once you get the tooling installed, the actual code you write isn’t particularly different. The module syntax looks a little wacky, but it’s literally like 2 lines of code.

To some extent, the parts people are finding difficult about getting started with Ember are the things that are difficult about getting started with modern web development. I’m not sure how much of that burden needs to be taken on by the site.

#6

Rails developers like me are very spoiled. We like code so stable we can cut and paste a 5 year old stackoverflow answer right into production!

I’d love to help with the docs, but I’m just getting started wtih ember. I could volunteer my services as a doc guinea pig and proofreader.

I’m liking ember and I want it to succeed, and I know documentation is a very important step. Its about presentation. If the docs are off, developers get very concerned about investing time and effort into something that might be going stale.

I see a cookbook area of the guides. There’s not much there, but that would be a great place to put the up to date ways of doing things. In just a week I cant tell you how many times I’ve found multiple ways of doing things, trying the wrong way first, deprecation warnings, etc. It would be like an dummies section of the canonical way of doing things.

Why doesn’t somebody who is knowledgeable and up to date just update the guides? It doesn’t look like that much work at all and would be a huge improvement to the site.

#7

Updating the documentation is a major, ongoing effort- huge rollouts in just the last week courtesy of @trek and friends. All of the examples use CLI now, and you shouldn’t get deprecation warnings for doing anything described in the guides. There is another fairly active thread with a call for cookbook recipes that people want, which everyone is encouraged to throw in on.

Ember requires a lot more from you up front. I don’t think that’s ever going to change. The trade-off is that the “back nine” of learning Ember is just a joy, and the homogeneity in the way people structure their apps makes switching between them effortless.

#8

Those documentation changes must have just happened. I guess I wasn’t the only one concerned about it :smile:

#9

The ember-cli and ember docs online are fine for me and my teams, don’t see a crisis here.

#10

Like I said, the docs just got a lot better. I’m pretty happy and I’m currently rereading them.

#11

As a neophyte that comes back to Ember every few months to see if it’s worth learning for my next project, I feel this pain. I think the issue isn’t about ember-cli being a scary command-line thing, but that it’s not yet mature.

Within five minutes of getting started, I found two issues with the CLI environment that were going to end up either blocking me or choosing a suboptimal user experience. That’s fine, the CLI is very much WIP, but now my options are:

  • Provide a lesser experience for my users using ember-cli as it is today
  • Use an older version of Ember until the CLI is ready, then upgrade
  • Reverse engineer the syntax of all the examples AND how to initialize an app Ember app in the first place

Which is the better option? I’m not sure.

#12

As a fellow neophyte and instigator of this post I’m making progress myself, but not that quickly.

Check out the guides on the site. They really have gotten better in the last week or so. They need some work but you won’t find the old way of doing things very often, however they are oddly devoid of the ember cli command line generators, but just keep in mind that it can generate controllers, routes, adapters, models, etc on the command line just like rails, so you won’t be struggling with where to put things, and getting the boilerplate wrong.

The other thing that helped me is never google “ember tutorial”. Always google “ember cli tutorials”. Sounds like a stupid suggestion, but it really helped. There are some good tutorials out there. I found this one useful http://ember.vicramon.com/

I haven’t found any print books useful, but I haven’t tried any of the self published ones.

I’ve been developing and learning new things for years, including some pretty obscure languages and I’ve never seen such an unwelcoming documentation situation. I honestly would have given up ember within a few days and tried an alternative if I hadn’t watched some video talks that convinced me it was the best choice.

#13

http://guides.emberjs.com/v1.10.0/

http://www.ember-cli.com/#generators-and-blueprints
The CLI documentation and Ember.js Guides are also in the process of being somewhat merged. The Guides will feature all the CLI documentation needed to develop and application, and the CLI website will feature documentation for addon developers.

You can paste most code, being the biggest change the deprecation of global-style in exchange for ES6 module syntax. Rails benefitted from a somewhat stable language, Ruby, underneath while the JavaScript environment is still being heavily iterated on. Thankfully CLI makes it easier to take advantage of ES6 features due to babel.js.

Outdated StackOverflow/blog posts were a problem pre-1.0 and now with the CLI change it can again be a problem, but it’s a switch that really had to be made since it improves on most things even if CLI isn’t 1.0 yet (June 12th gets nearer by the day! :wink:

#14

Just to add to the copy and paste from Stackoverflow and the docs, I forked a project that was started long before Ember-CLI, a project that was using grunt and some old yeoman generator. I took it over to ember-cli with relative easy by generating fresh files using the generators and then pasting in the bodies of my old global objects. I fixed plenty of jshint warnings, a few deprecation warnings (this was from 1.5 to 1.10), and actually added proper tests. The most “pain” was from updating the templates. It was a big manual undertaking, but rewarding.

I understand this creates some confusion, and folks that are familiar with the process forget what it takes. Everyone needs this kind of feedback to help new users grow into ember & ember-cli easily. Everything said here will probably make its way into the project in one way or another, so stay put!

Although very rough around the edges, the experience is already amazing and getting polished every single day. To build ambitious applications, you need ambitious tooling built by an ambitious community.