Suck it up and be a noob

Posted on Mon 17 September 2012 in Opinion

This is a whine post, but I really need to get it out of my system. Apologies in advance!

I’ve battled with Angular for a while now. It’s a JavaScript framework that allows you to write rich client-side applications in very short time with goodies such as two-way data binding, route handling and view-controller separation.

In theory, that is.

In practice, writing an application using Angular takes a long time and is a journey filled with pain, frustration and dead ends. And the main reason is this:

The documentation sucks!

There’s no nicer way to say it. The documentation is incomplete, incorrect and outdated. To further add insult to injury, examples on the web are likely to apply to an older version of Angular and not work with the newest version, since backwards compatibility was broken somewhere along the way.

In defense of the Angular developers, writing documentation is hard and boring. I’ve worked with API development, and the documentation was always a sore point, and was many times addressed as an afterthought. But that’s an explanation, not an excuse! No matter how feature-rich and powerful a framework is, bad documentation is a big and ugly problem. And Angular is not alone - there are countless frameworks out there with sub-standard documentation. Microsoft’s .NET framework is one of them.

So how do you deal with bad documentation? You do one or both of the following:

  1. Become a noob! As soon as you run into a problem, however tiny it is, ask on the mailing list! Don’t bother consulting the documentation, because it’s likely to lead you in the wrong direction anyway.
  2. Be a good open source citizen and contribute what you’ve learned the hard way to the documentation, so that others may benefit from it!

Generally speaking, noob behavior doesn’t come naturally to me. I usually spend a long time researching problems I run into before asking, because I don’t want to appear uninformed. But Angular has made me re-think this!

I have a number of contributions I want to make to Angular’s documentation. I will post at least some of them on this blog also, in the interest of spreading the knowledge.

Stay tuned!

P.S. On a side note, I’ve seen the phrase “designed with love” used for a number of frameworks (all web, IIRC). I’ve never seen “documented with love!” ;-)