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