6 ms·

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

"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 ago
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.
- 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 ago
    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.
    - stretchwithme 13y ago
      Those who understand how to do should teach.
    - stock_toaster 13y ago
      > 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".
    - 13y ago
steveklabnik 13y ago
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.
- Foxandxss 13y ago
  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.
- sanderjd 13y ago
  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.
ams6110 13y ago
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 13y ago
  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 13y ago
    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 13y ago
      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.
- kawera 13y ago
  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"?

jacques_chester 13y ago

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.

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 ago
  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.
  - stretchwithme 13y ago
    Those who understand how to do should teach.
  - stock_toaster 13y ago
    > 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".
  - 13y ago

steveklabnik 13y ago

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.

Foxandxss 13y ago
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.
sanderjd 13y ago
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.

ams6110 13y ago

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 13y ago
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 13y ago
  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 13y ago
    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.
kawera 13y ago
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"?