Alright, so maybe they don’t suck, I don’t know. That’s half the problem. The documentation is so bad though that I’ll never know. They have huge, multi-hour tutorials to make the one and only Todos app, which cover things off in such limited scope that you better hope your day job is making Todo list applications, because that’s all you’ll be able to do after covering off one of those behemoth tutorials.
I went through the AngularJS tutorial, and it was fine and dandy. Really awesome stuff, honestly. As someone who hates writing anything to manipulate the DOM, the way it reduces me having to even think about it is great. But what about forms, and validation? They’re seriously the number two thing you’ll do with a framework. The learning cycle of web frameworks is roughly this;
- Get “Hello World” out.
- Put “Hello Computer” in.
- Judge harshly and proclaim yourself an expert.
And a lot of the tutorials I found for Emberjs, Backbonejs, AngularJS, SammyJS, did not cover off number two. Alright I lied. None of them. I found some awful tutorials that covered it off in a horrible way, but that was it. So I’m given this great framework, but shitty documentation, so I can’t figure out how to easily submit forms and have them validate nicely. Feels like Dojo all over again. The worst part is that the API documentation for these frameworks is usually surprisingly good, but severely lacking on context in the examples, so it’s hard to get something working. I mean, with regards to forms, I checked out the AngularJS API docs and found it in seconds, but with hardly enough information to do anything with it.
I mean, I have no doubt that these tutorials exist, and that the frameworks can probably do what I want them to, but I shouldn’t have to look much further than the documentation to find out how to do something so basic.
I guess the real problem I have with these frameworks is that they all claim to be huge time-savers, but the documentation is so poor that it’s hard to justify how much time they could actually save you, at least when you’re getting started. You pour hours of your time into learning one of these frameworks, just to find out it was actually the worst possible choice, or the real documentation sucks. That and the assumption of knowledge on some of the tutorials is horrendous - AngularJS wants you to use Node and Git, just to work through the tutorial. I use Python and Mercurial dammit, get off my lawn.
Every step also features a huge lecture on testing the particular part you’ve just learnt. I understand where they’re coming from, and what they’re trying to do, but testing applications is worth an entire tutorial in and of itself.
A middle ground would be nice - cookbook style documentation usually helps everyone. Let’s all do that.
No, I’m not done yet. When did screencasts become an acceptable way to deliver tutorials and documentation? You can’t print them. You can’t search them. Even as the creator you can’t easily fix errors or update them. Stop it. Bad. Only do these things when it makes sense. Videos as the canonical reference material for your framework does not make sense.
With that rant done, I can say that AngularJS definitely does seem to be the
$('#foo') once and that makes me very happy.