Hacker News Reader

Comment by gkoberger | Hacker News Reader

The worst part of 1.3 (well, anything > 1.2.2) is they're removing comments from their documentation. The docs are already abysmal; now they're removing the only part of the docs that was decent (since people would post solutions to common problems).

Although, to be fair, half the Disqus comments were just complaining about how bad the docs were.

http://blog.angularjs.org/2013/11/farewell-disqus.html

View on HN

Angular's Disqus comments were a perfect example of the hate and entitlement in open source that makes people quit contributing. While they're not the greatest docs, they're quite passable, especially with the rest of the info on the web (videos explaining concepts, egghead.io, etc). On top of that, it is really easy to contribute. I saw a few small doc issues, fixed them, and they were merged within 6 hours. If people could be more civil and constructive, comments would be fine, but I'm glad they're gone.

> If people could be more civil and constructive, comments would be fine, but I'm glad they're gone.

So it's better to just ignore the problems with the documentation? I barely have time to learn the framework—the lack of good documentation means I delete it from my hard drive. No matter how good a framework is, if it's not documented well, it's a buggy black box.

Even criticism that doesn't offer a solution is better than a lack of feedback. Besides, it's not like Google will get all self conscious and stop contributing because people don't think the documentation is good.

> I barely have time to learn the framework.

If you can't be bothered to deeply study and understand your tools then you probably don't deserve to use them anyway.

duaneb doesn't have much time to learn one particular framework, so you think he doesn't deserve any tools?

Wha?

Yeah totally. And if you can't be bothered to read your car's owner's manual from cover to cover you probably don't deserve to be driving it anyway.

A lack of curiosity is indeed reproachable. And while I do consider knowing how a car works basic common knowledge, I wouldn't advise someone that doesn't have that to start with the manual.

Actually, you should probably read the Chilton (or equivalent) manual cover to cover.

This isn't the context of people using Angular the hammer, it's in the context of people trying to learn Angular, the forklift, and all of the forklift users saying "It's not our fault you can't figure it out!"

> If you can't be bothered to deeply study and understand your tools then you probably don't deserve to use them anyway.

I hadn't even gotten past the evaluation stage. Bad documentation is a huge smell for the rest of the framework—I'm not going to waste my time pursuing a tool that I'm not going to use.

There are plenty of places to offer feedback on Angular, general or specific. All I'm saying is that it's nice to look at the docs and not have to see a big string of "OMG AngularJS docs suck" (only a slight exaggeration).

Also, if your comment is going to be useful on a documentation page, chances are it will be even more useful as a commit to the docs themselves. Mad about doc quality? Whine (give feedback) about it on Twitter, maybe even mention one of the committers.

>Angular's Disqus comments were a perfect example of the hate and entitlement in open source that makes people quit contributing.

This is a perfect example of the entitlement people feel to be free from others' ire or criticism.

Opening up the Angular documentation to have a look, it appears that every page has an "improve this doc" button, which allows you to submit a pull request to get the official documentation changed. Surely if you find that the documentation is unclear, it's better to add a note or a clarification directly into the documentation than write a comment?

>> , which allows you to submit a pull request

well , it would mean you can understand it at first place...

If the documentation is so bad. Are there any books available that would help?

Try the following

    - AngularJS http://shop.oreilly.com/product/0636920028055.do
    - Web Application Development With AngularJS http://www.packtpub.com/angularjs-web-application-development/book

Have you read either of them? Don't recommend books you haven't read. I know for a fact that the O'Reilly book is crap.

I am currently reading "Web Application Development With Angular". Its a well written book geared towards who already know angular basics. That's why I suggested O'Reilly book as its introductory which explains angular core concepts.

Another book worth looking at is: Recipes with Angular.js which is covered under Leanpub Unconditional Return Guarantee. so if you don't like the book. 45 days of purchase you can get a 100% refund.

    https://leanpub.com/recipes-with-angular-js

so you can try the above, if you don't like the other two

Sadly I agree that the O'Reilly book is of poor quality. Bad editing, sloppy writing style, terrible organization of the chapters. Whatever happened to O'Reilly's standards?

The Mastering Web Application Development book is pretty good I felt.

Reply on news.ycombinator.com