13 ms·
Angular is god's gift to programming bloggers. The documentation is so famously patchy, contradictory and impenetrable that an entire cottage industry of talmud
by jacques_chester 13y ago
Angular is god's gift to programming bloggers. The documentation is so famously patchy, contradictory and impenetrable that an entire cottage industry of talmudic literature has sprung up around it overnight.
I've spent the last two weeks slicing and dicing the developer guide and all the directly related API documentation -- this one-page demo is better than the entire Angular tutorial. It also covers the most important 20% of the Developer Guide.
Based on my current understanding, I'd explain Angular in a different direction. Everyone starts with the binding, introduces a few inbuilt directives, then possibly writes a directive.
I'd start with the $digest() loop, then build out to the runtime loop generally, then explain how link()ing makes the $digest() loop possible via $watch().
There is an enormous amount of Angular that is damn near liable to cause you to scratch your head clear through to your grey matter unless you spend 15 minutes reading the $digest() source code and eyeballing the dev guide in a few places. The docs by themselves simply will not teach you how Angular works, which rather falls short of the purpose of having documentation.
- Foxandxss 13y agoI totally agree with you. That is one of the reasons I created this blog. I am 24/7 in #angularjs in freenode and I see questions repeated over and over again. My goal is to write about those solutions we give to them so they won't need to ask again. On the other hand, my goal was to "sell" angular to the readers, not to scary them with $digest issues :) Said that, I have in my TODO things about this matter.
- waterside81 13y agoI'm quite experienced with JS, jQuery etc. but never really "got" what Angular was all about. This is the first time the light bulb went off - so thanks for a great write up.
- mgkimsal 13y ago"The docs by themselves simply will not teach you how Angular works." Well said, and I agree, but I wonder why this is? There's some cred to be gained by making and using something so impenetrable that only a select handful of people 'just know' how something works, and everyone aspires to be like them? I've found plenty of people/blogs/sites telling me I'm doing angular 'wrong' (and not just angular - other frameworks/libraries) but precious few people can demonstrate a 'right' way to do things which actually accommodates real world use cases. On top of that, what was canonical at one point is later made obsolete via a single patch/push, but the blogosphere/google never quite catch up. Less an angular-specific rant, more an observation as to how more projects seem to be heading. As I become one of the 'older' generation, I'm seeing more younger devs (under 25, less than 3 years of professional experience) embracing this code lifestyle, and seem to think it's great, and old fogeys like me just 'can't keep up'. Maybe I can't, but perhaps if you'd document your stuff a bit more, we could just use the library instead of having to read every single line of code, commit, watch for patches, finagle and beg to get pull requests taken and used, and pray that the next point release doesn't break everything. Obviously not all projects are like this, but it seems there's a growing trend among younger projects to work this way. Or maybe I'm just getting old...
- jacques_chester 13y agoThey say that great athletes make bad coaches. Why? Because they can't explain what came instinctively. Similarly, the wrong person to write documentation is the creator of a system. He or she will not know what leaps of understanding are being made throughout the text. That's why big IT companies have historically hired technical writers, which is a profession in its own right. Those general observations aside, I believe that for some of the Angular team English is a second language. But otherwise, in the case of the Angular docs, there is a simple lack of attention to detail. Poor fit and finish. It's pretty clear that a lot of the documentation is the first draft. In the comments you can always find someone complaining and someone else saying "fork it on github". If you actually go and look at github, there are hundreds of unanswered pull requests. So clearly that isn't working either.
- mgkimsal 13y ago"But otherwise, in the case of the Angular docs, there is a simple lack of attention to detail. Poor fit and finish. It's pretty clear that a lot of the documentation is the first draft." Spot on. "In the comments you can always find someone complaining and someone else saying "fork it on github". If you actually go and look at github, there are hundreds of unanswered pull requests. So clearly that isn't working either." Agreed. I would disagree that the person/team writing something isn't fit to document it. Yes, sometimes they're not the best choice, but often they're the only person, and there's no 'choice' at all.
- api 13y ago"They say that great athletes make bad coaches. Why? Because they can't explain what came instinctively." Thank you for finally explaining to me why mathematicians are such famously bad teachers of math. They just start scribbling symbols without explaining what they mean because of course you know what they mean...
- jacques_chester 13y agoI first heard it from one of the world's most experienced weightlifting coaches, Lyn Jones. It explained a lot to me too. The corollary is that people who love something, but can't do it easily, tend to be good coaches. Because they've had to really make an effort and have diligently sought out ways to improve themselves. Put another way: "those who can't do, teach" isn't an insult to teachers. It's praise.
- patrickaljord 13y agoThey're working on new docs that are much better, see here: * http://code.angularjs.org/1.1.5/docs/api http://code.angularjs.org/1.1.5/docs/api There's also a interactive tutorial that's being worked on (it used to be online but not anymore). See the presentation here: https://docs.google.com/presentation/d/1WHCcp3G3HxoE7b_ut_ERKJF4zQK_P4qFlESjE2E9AUQ/edit#slide=id.geaf70e8e_115 https://docs.google.com/presentation/d/1WHCcp3G3HxoE7b_ut_ER...
- jacques_chester 13y agoThat is good news. However, the dev guide looks identical. People don't, as a rule, read reference documentation cover to cover and then somehow spontaneously grok the principles of operation.
- Oculus 13y agoMy way of looking at it was always Documentation the Angular Way:
- oinksoft 13y agoThe documentation is not impenetrable, it is just that AngularJS is a library that takes a while to get up to speed on. What is lacking right now is writing on best practices and application design. The O'Reilly book offers some of this, but generally it's just a warm-up with a couple case studies at the end. http://docs.angularjs.org/guide/concepts http://docs.angularjs.org/guide/concepts is a model of good documentation, and http://docs.angularjs.org/guide/directive http://docs.angularjs.org/guide/directive is exhaustive. The most difficult parts of the framework are very well-documented, but that some parts of the API have been woefully overlooked. As you can see in that first link, Angular is an elaborate framework, and there is a lot to stuff in your head at once. This is why newcomers find the learning curve steep: It is a new way to write applications.
- at-fates-hands 13y ago>>This is why newcomers find the learning curve steep: It is a new way to write applications. As someone who's run the gamut of "trendy" JS frameworks, I picked up Angular much faster than Backbone, Ember and Knockout combined. Maybe it's the MVC thing, I don't know, but something just clicked with me with Angular. After watching a few tutorials, I able to build something from scratch without much effort.
- KurtMueller 13y agoMaybe it's because you picked AngularJS last and spent your learning curve / wtf-moments on the previously mentioned frameworks.
- pm 13y agoI wanted to use it, but couldn't use it with Bootstrap (I know), so it was back to CoffeeScript and Backbone for me.
- dchuk 13y agoYou can use either angular ui or angularstrap to get native angular support for bootstrap
- meowface 13y agoThis is kind of a dumb question, but do you know of any good solutions that allow the use of Angular with CoffeeScript, Bootstrap, AND a higher-level templating language like HAML? (I know I'm pretty much combining "hip" programming buzzwords here, but I am curious.)
- xaritas 13y agoI haven't used it, but I think this might be what you are looking for: https://github.com/tuyen/yeoman-angular-haml https://github.com/tuyen/yeoman-angular-haml Based on yeoman (http://yeoman.io http://yeoman.io), which I used briefly for the first time a few days ago, and it seems like a nice system. It already has pretty good integration with the AngularJS seed project. You could probably roll something together using middleman (http://middlemanapp.com http://middlemanapp.com) too, with a bit more legwork.
- anton-107 13y agoAngular + Bootstrap = use Angular UI Bootstrap. For Coffee use on-the-fly transcompilation of your choice (i.e. grunt-contrib-coffee + grunt-contrib-watch). For any of higher-level templating again use on-the-fly compilation (i.e. grunt-haml + grunt-contrib-watch)
- 6ren 13y agoA programmer once pointed out to me that my project wasn't "cool" because it was too easy to use. There were no bragging rights; using it didn't impress anyone. Therefore, to get the aura of cool, make it a bit impenetrable. Then, initial users get to feel valuable by passing on the sacred holies to the next tier of disciples, and so on, this arcane oral tradition enforcing social hierarchies of "competence", in mockery of the technology adoption life-cycle. It's similar in social effect to the initial artificial scarcity of gmail. Bonus: bloggers give you free publicity. Every extra post squeezes out more google juice. In addition, if you have to work for it, you value it more. And you'll remember it better. And because it remains difficult to use, your hard-won skills retain their value. Worked for git and unix. (Of course, it also has to be useful).
- regularfry 13y agoThat programmer was a pillock.
- rdtsc 13y agoMy personal view if it is too hard or complicated to write documentation, too hard and complicated to explain how it works, then it is not worth doing. I tried looking at it and got lost in lots magic $scope, $directives and other arcane constructs. Yes I would have probably liked to have it described how you suggest, start with how it works.
- pekk 13y agoIs this not also true of Ember, ... ?