[jacques_chester]

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.

[mgkimsal]

"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]

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

[api]

"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]

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

[IsaacL]

Great quote from George Leonard's Mastery:

"In his book Zen Mind, Beginner’s Mind, Zen master Shunryu Suzuki approaches the question of fast and slow learners in terms of horses. “In our scriptures, it is said that there are four kinds of horses: excellent ones, good ones, poor ones, and bad ones. The best horse will run slow and fast, right and left, at the driver’s will, before it sees the shadow of the whip; the second will run as well as the first one, just before the whip reaches its skin; the third one will run when it feels pain on its body; the fourth will run after the pain penetrates to the marrow of its bones. You can imagine how difficult it is for the fourth one to learn to run.

When we hear this story, almost all of us want to be the best horse. If it is impossible to be the best one, we want to be the second best.” But this is a mistake, Master Suzuki says. When you learn too easily, you’re tempted not to work hard, not to penetrate to the marrow of a practice.

“If you study calligraphy, you will find that those who are not so clever usually become the best calligraphers. Those who are very clever with their hands often encounter great difficulty after they have reached a certain stage. This is also true in art, and in life.” The best horse, according to Suzuki, may be the worst horse. And the worst horse can be the best, for if it perseveres, it will have learned whatever it is practicing all the way to the marrow of its bones."

(Shameless self-plug - I wrote a blog post about this a while ago: http://i.saac.me/post/lurning-cearves/)

[stock_toaster]

  > Put another way: "those who can't do, teach" isn't an insult to teachers. It's praise.

Maybe that old saying should be rephrased to "those who can't instinctively do, teach".

[api]

That's actually incredibly optimistic... it means if someone has to struggle really really hard to get something, they're quite possibly better to teach it to others. The struggle itself imparts a unique skill that those that get it more "naturally" might not have.

[stretchwithme]

Those who understand how to do should teach.

[mgkimsal]

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

[pkozlowski_os]

Let's be precise - at the moment there are exactly 68 open pull requests, _one_ of them being about documentation: https://github.com/angular/angular.js/pulls

There is a huge difference in the open source world between ranting and actually doing something about your pain-points.

[paulwithap]

One open pull request, but every single page of the documentation is filled with comments from confused people asking for better docs. Fortunately, there's also sometimes a comment giving a proper explanation of that piece of the API.

[chroto24]

Sounds like the PHP docs

[jacques_chester]

There were more when I first checked.

Besides, it's hard for me to fix that I couldn't understand the docs when starting from the position of ... not understanding the docs.

[marincounty]

1. Yea, I agree. 2. This industry(Comuter Science) is not taught very well. 3. I cringe when I see those 500 page "manuals".

[ams6110]

What these "younger devs" don't realize is that in most cases they are simply reinventing stuff that has existed for years. Even today, the best JS MVC frameworks only just provide the capabilities to build UIs that (for example) were trivial in PowerBuilder 20 years ago.

The fact that it's considered "gee whiz" that you can enter a value into a form field and have that value automatically validated and bound to an attribute in a "model" shows how little we have really advanced.

Web UIs offer a lot in the way of visual styling and easy distribution... but the actual building of apps hasn't really advanced much.

[jacques_chester]

I sometimes wonder what the world would look like if somehow it was all hypercards or DCOM or OpenDoc or NeWS or just about anything other than a simple document format painfully hammered into the shape of an applications platform.

[jfb]

It's fun to run the counterfactuals, but ultimately, we go to war with the lousy technology stack we have, not the mediocre one we want. I'm just overjoyed that, thanks to Android and iOS, people are writing native applications again.

[SimHacker]

There are known IKnowns: there are APIs we know that we know. There are known IUnknowns: that is to say, there are APIs that we now know we don't know. But there are also unknown IUnknowns: there are APIs we do not know we don't know.

[timmy-turner]

Just reinventing the wheel to not having to use Powerbuiler makes a lot of sense to me. Even if it takes 20 years. Even if it only covers the trivial features. 5 years ago, I used to work on two huge Powerbuilder projects. I don't remember having real models or support for them in Powerbuilder and these projects. Everything was just datawindows, embedded SQL and stored procedures. I'm really glad that I'm now working on a web application at a different company.

[kawera]

What these "younger devs" don't realize is that in most cases they are simply reinventing stuff that has existed for years.

And this is also true for so many aspects of the modern "stack" - remember "time sharing"?

[rdtsc]

"Those that don't learn from history are bound to repeat it"

This includes both repeating the mistakes and design issues, but also getting excited about the "invention".

[dirtyaura]

I wouldn't say that Angular is reinventing the wheel. Elegant and efficient two-way data binding is a non-trivial problem, and I haven't seen it implemented well (or at all!) in any UI framework that I have worked with in the last 15 years.

[mickeyp]

Delphi had amazing data binding. You literally dropped two non-visual components on your form; plonked down data-aware components; and then pointed it at any number of databases via ADO, DAO, ODBC or BDE and you were flying.

Unrivalled flexibility and power and you could do knock together a CRUD app in a couple of hours.

Add to that the incredible flexibility afforded by 3rd party components like DevExpress and you had grids and other tabular components that even today any amount of HTML5, JS and CSS and backend programming could only dream of achieving.

And we did this in the 90s.

[warfangle]

How was it at near-platform-universality and secure HTTP transmission?

[jacques_chester]

Windows was the near-universal platform and fairly sophisticated networking ability was inbuilt.

[coldtea]

You mean getting something else (that's orthogonal) in exchange, justifies a regression to pre-90's in other areas?

[icedchai]

It's so true... It's sad we've wasted so much effort putting square pegs in round holes.

[steveklabnik]

Writing documentation is really hard.

It's also hard to get people to contribute to documentation. I had a conversation with someone recently that was frustrated about the Rails documentation: "Here's my blog post about how to do X. Apparently that's what Rails people do rather than write docs." When I asked why they didn't contribute to the docs rather than make Yet Another Blog Post that feeds into the exact problem they were talking about, it just hadn't actually occurred to them. Getting started contributing to a new project is difficult, posting something to your blog is easy.

Most people don't find writing docs to be fun, and Open Source is largely driven around doing what's fun.

It's hard to see the flaws in something you're close to. The people who are closest to a project forget how hard it is to come in from nothing; I had a conversation recently about Hackety Hack where someone was upset it didn't have the ability to make folders and multi-file projects, and when I tried to explain to them that the beginners (children and adults) that I teach actually struggle with things like file management, they were shocked. We all forget just how much we know, because it's easy to us!

Furthermore, there's an incentive for people to write blog posts over contribute to official docs, since then people will link to their blog, with all the benefit that comes along with.

I am not informed on the state of Angular's documentation, and I think Rails has pretty decent docs these days, but there's lots of reasons why docs are often poor in open source projects.

[rdtsc]

> Writing documentation is really hard.

If that is the case then one should wonder about the project itself. If the idea and functionality cannot be easily expressed then one wonders whether that project is worth pursuing.

I stopped being interested in the project. I did look at the source and all the magic going on behind the scenes and didn't like what I saw. It reminds of those large frameworks management would buy for big enterprises and say "just use this, this will be really easy, we'll increase the productivity 100%!".

[sanderjd]

I realized something recently about docs-vs-blogs. An important difference between the two is that official documentation of a project is the place to say "this is how it is done", whereas blogs are a place to say "this is how I do it". If there isn't a consensus on how something should be done, but you think the way you do it is nice, it definitely makes sense to write about that in a blog post, but it only possibly makes sense to propose your way for official documentation.

I think it took all those blog posts to generate all the consensus necessary to make the "pretty decent" (I would say "very good") Rails docs possible.

[pixelcort]

An official blog can be, "This is how it is done, as of the time of posting."

However, then you end up with blog posts like, "here what's new in 3.5", without any documentation for users who never used 3.4 (or 3.3, 3.2...)

[Foxandxss]

You made a good point here. That point of view will prove to be useful to me :)

[regularfry]

My very first PR to the Emberjs project was an improved entry-level tutorial, just to work people past the pain points I'd experienced getting up and running following the then-current getting started guide (which were neither few, nor far between). The initial response? "This would be better as a blog post."

[mgkimsal]

WOW - that's crazy. Thanks for a recent real world example.

[Foxandxss]

I agree with you.

I don't feel I have the experience to write better angular docs. That could be a goal in a future for sure.

Even when I am going to write about things that could be used to improve the official docs, one of my main goals is to answer via blog the questions I see everyday: "Why this doesn't work?", "My directive is not doing what I need", "My service is not updating"...

I think that the documentation itself needs to be done from various angles, and this is one for me.

[pm]

Documentation is hard because those who are documenting assume too much about those who are learning. This concept applies as much to closed source projects as it does to open source projects. It's all a matter of being open to those who are learning, and incorporating what they don't understand.

[6ren]

A 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]

That programmer was a pillock.

[patrickaljord]

They're working on new docs that are much better, see here:

* 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_ER...

[jacques_chester]

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

[Foxandxss]

I 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]

I'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.

[oinksoft]

The 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 is a model of good documentation, and 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]

>>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]

Maybe it's because you picked AngularJS last and spent your learning curve / wtf-moments on the previously mentioned frameworks.

[rdtsc]

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

[Oculus]

My way of looking at it was always

Documentation the Angular Way:

[pekk]

Is this not also true of Ember, ... ?

[pm]

I wanted to use it, but couldn't use it with Bootstrap (I know), so it was back to CoffeeScript and Backbone for me.

[dchuk]

You can use either angular ui or angularstrap to get native angular support for bootstrap

[meowface]

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

[anton-107]

Angular + 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)

[xaritas]

I haven't used it, but I think this might be what you are looking for: https://github.com/tuyen/yeoman-angular-haml

Based on yeoman (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) too, with a bit more legwork.