5 ms·

I really really want to try loving AngularJS, and to some extent i really do -- but when I need to look at the documentation, I feel like shedding tears. Angul

I really really want to try loving AngularJS, and to some extent i really do -- but when I need to look at the documentation, I feel like shedding tears. Angular-team: You have an awesome product. Please fix your documentation, and include examples usable with angular-seed, instead of the standalone-examples. Has the documentation improved with 1.2?

sbegaudeau 13y ago
The documentation has been improved multiple times with the 1.2 release: https://plus.google.com/u/0/+BradGreen/posts/EFLVQ2pTfHG https://plus.google.com/u/0/+BradGreen/posts/EFLVQ2pTfHG https://plus.google.com/u/0/+BradGreen/posts/Pocnw7VLhxU https://plus.google.com/u/0/+BradGreen/posts/Pocnw7VLhxU https://plus.google.com/u/0/+BradGreen/posts/NzS6bJtMc2f https://plus.google.com/u/0/+BradGreen/posts/NzS6bJtMc2f
ds_ 13y ago
The documentation isn't great but it isn't terrible either. I hope people thinking of giving angular a try aren't put off by the constant over-dramatisation.
- k__ 13y ago
  Yeah, I don't think the docs are bad, angular is just not a simple concept.
- Cthulhu_ 13y ago
  And their lack of attempts to improve it; I mean, it's an open source project, there's a big "IMPROVE THIS DOC!" button on every documentation page.
  - deleted 13y ago
    [deleted]
  - spyder 13y ago
    Maybe it's because improving the doc has not too much benefit for the contributor because he/she already understands the badly documented problem. But improving code has instant benefit for the contributor because he probably fixing something he still using.
    - hysan 13y ago
      I think the simpler answer is that most people who complain about documentation cannot improve the docs because they don't know how. If they did understand what was being explained in the documentation, they wouldn't be complaining in the first place.
      - randallsquared 13y ago
        This is actually the same answer: when they finally learn enough to fix the documentation, there is no longer any personal benefit to doing so.
        mst 13y ago
        This is why my projects have always been willing to cut a deal with newbies to exchange stupid question credits for doc patches - i.e. "if you feel X is underdocumented, the core team will happily give you a personal tour of X provided you write up the results for the next guy to read" - which tends to help the incentive problem.
        hysan 13y ago
        I was trying to make the distinction between those who get to the level of competence of contributing vs those who don't reach that point. The former group being people who don't complain about the docs (or at least not as loudly) while the latter group does. But I guess I didn't get that across clearly, sorry.
mackwic 13y ago
Documentation got waaay better these last weeks. Hope that continue. About examples, we can't point enough the awesome work of the Angular-ui team. I think their code is near the state of the art of Angular. But yep, a big complete applications using Angular in which we can digg into would be nice. In my experience, Code Scalings THE problem you got with your real world application. Restangular helps. A lot. Services are not that useful, Factories even less (but when they are, it's a neat feature), and Providers are simply something internal that we can optionally use if we want do some meta-meta-programming (factories do the first meta). I hope the guideline for the next release will be to get rid of the over-engineering that makes everything complex when you need to do something UI-dynamic (ever try to attach dynamically a tooltip ?). Sometimes Angular just go on your way and don't want to move. The things I would want to be changed: - Remove Providers. that's just redundant with factories, with the only exception as some complex internals we shouldn't use anyway - Remove $rootScope. It's an internal thing that should not be used. - Make $q better. It's a pain to use. Really. - Better control to digests (monitoring, postponing mostly) - Angular binding with CSS would be awesome. But it needs some work to make a clean separation. - Directives. Seriously: the way to declare them really should be changed. Returning this starnge object, what the point ? What about Directives Factories for all the multiple ways to declare them, and in last resort only, using the weird object when you need that fine grained control. Mixing all together like the current state is not viable.
- aidos 13y ago
  Could you explain a bit more about the tooltip issue you've mentioned? I'd be interested to explore to understand what the limitation is and how I (or others) might approach it. I'm not sure I agree with all of your comments. I find that services are relatively essential building blocks for my applications. Providers are there so that you can preconfigure your modules. It's a legitimate use case. Take Restangular, for example - it's so useful to you because it's a provider that you can configure for your app. I can see how $rootScope could be perceived as code smell but after examining how angular uses it internally I'm ok with the way I use it. Directives are confusing the first time you see them. You need to see a few examples. Though I don't think there's a problem with the api for declaring them. There's a lot to configure - it's mostly optional, but you may well need all of it eventually. Angular gives you a framework to build on. You can create really amazing components that are totally reusable on your other projects. Sometimes they come in the form of directives, sometimes they're other types of module. Often when you start abstracting that out you'll need to get a bit closer to the metal. Angular provides an api for you to work with in those cases and it's ok to take advantage of that.
cheshire137 13y ago
I do love and use AngularJS, but finding solutions to problems I have with it seriously the most frustrating experience I've had with any language. It can be a real pain going from Ruby on Rails development, for which there is always a gem or a couple-line fix for a given problem, to AngularJS. Sometimes I find a solution by cobbling together StackOverflow answers, sometimes random Google Groups posts and JS fiddles, but I never find the answer in the AngularJS docs. I use the official documentation only as a reference when I already know what I'm doing and only forgot the name of some property.

sbegaudeau 13y ago

The documentation has been improved multiple times with the 1.2 release: https://plus.google.com/u/0/+BradGreen/posts/EFLVQ2pTfHG https://plus.google.com/u/0/+BradGreen/posts/EFLVQ2pTfHG https://plus.google.com/u/0/+BradGreen/posts/Pocnw7VLhxU https://plus.google.com/u/0/+BradGreen/posts/Pocnw7VLhxU https://plus.google.com/u/0/+BradGreen/posts/NzS6bJtMc2f https://plus.google.com/u/0/+BradGreen/posts/NzS6bJtMc2f

ds_ 13y ago

The documentation isn't great but it isn't terrible either. I hope people thinking of giving angular a try aren't put off by the constant over-dramatisation.

k__ 13y ago
Yeah, I don't think the docs are bad, angular is just not a simple concept.
Cthulhu_ 13y ago
And their lack of attempts to improve it; I mean, it's an open source project, there's a big "IMPROVE THIS DOC!" button on every documentation page.
- deleted 13y ago
  [deleted]
- spyder 13y ago
  Maybe it's because improving the doc has not too much benefit for the contributor because he/she already understands the badly documented problem. But improving code has instant benefit for the contributor because he probably fixing something he still using.
  - hysan 13y ago
    I think the simpler answer is that most people who complain about documentation cannot improve the docs because they don't know how. If they did understand what was being explained in the documentation, they wouldn't be complaining in the first place.
    - randallsquared 13y ago
      This is actually the same answer: when they finally learn enough to fix the documentation, there is no longer any personal benefit to doing so.
      - mst 13y ago
        This is why my projects have always been willing to cut a deal with newbies to exchange stupid question credits for doc patches - i.e. "if you feel X is underdocumented, the core team will happily give you a personal tour of X provided you write up the results for the next guy to read" - which tends to help the incentive problem.
      - hysan 13y ago
        I was trying to make the distinction between those who get to the level of competence of contributing vs those who don't reach that point. The former group being people who don't complain about the docs (or at least not as loudly) while the latter group does. But I guess I didn't get that across clearly, sorry.

mackwic 13y ago

Documentation got waaay better these last weeks. Hope that continue. About examples, we can't point enough the awesome work of the Angular-ui team. I think their code is near the state of the art of Angular. But yep, a big complete applications using Angular in which we can digg into would be nice. In my experience, Code Scalings THE problem you got with your real world application. Restangular helps. A lot. Services are not that useful, Factories even less (but when they are, it's a neat feature), and Providers are simply something internal that we can optionally use if we want do some meta-meta-programming (factories do the first meta). I hope the guideline for the next release will be to get rid of the over-engineering that makes everything complex when you need to do something UI-dynamic (ever try to attach dynamically a tooltip ?). Sometimes Angular just go on your way and don't want to move. The things I would want to be changed: - Remove Providers. that's just redundant with factories, with the only exception as some complex internals we shouldn't use anyway - Remove $rootScope. It's an internal thing that should not be used. - Make $q better. It's a pain to use. Really. - Better control to digests (monitoring, postponing mostly) - Angular binding with CSS would be awesome. But it needs some work to make a clean separation. - Directives. Seriously: the way to declare them really should be changed. Returning this starnge object, what the point ? What about Directives Factories for all the multiple ways to declare them, and in last resort only, using the weird object when you need that fine grained control. Mixing all together like the current state is not viable.

aidos 13y ago
Could you explain a bit more about the tooltip issue you've mentioned? I'd be interested to explore to understand what the limitation is and how I (or others) might approach it. I'm not sure I agree with all of your comments. I find that services are relatively essential building blocks for my applications. Providers are there so that you can preconfigure your modules. It's a legitimate use case. Take Restangular, for example - it's so useful to you because it's a provider that you can configure for your app. I can see how $rootScope could be perceived as code smell but after examining how angular uses it internally I'm ok with the way I use it. Directives are confusing the first time you see them. You need to see a few examples. Though I don't think there's a problem with the api for declaring them. There's a lot to configure - it's mostly optional, but you may well need all of it eventually. Angular gives you a framework to build on. You can create really amazing components that are totally reusable on your other projects. Sometimes they come in the form of directives, sometimes they're other types of module. Often when you start abstracting that out you'll need to get a bit closer to the metal. Angular provides an api for you to work with in those cases and it's ok to take advantage of that.

cheshire137 13y ago

I do love and use AngularJS, but finding solutions to problems I have with it seriously the most frustrating experience I've had with any language. It can be a real pain going from Ruby on Rails development, for which there is always a gem or a couple-line fix for a given problem, to AngularJS. Sometimes I find a solution by cobbling together StackOverflow answers, sometimes random Google Groups posts and JS fiddles, but I never find the answer in the AngularJS docs. I use the official documentation only as a reference when I already know what I'm doing and only forgot the name of some property.