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.

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

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.

"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/)

  > Put another way: "those who can't do, teach" isn't an insult to teachers. It's praise.

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.

There is a huge difference in the open source world between ranting and actually doing something about your pain-points.

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.

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.

And this is also true for so many aspects of the modern "stack" - remember "time sharing"?

This includes both repeating the mistakes and design issues, but also getting excited about the "invention".

Unrivalled flexibility and power and you could do knock together a CRUD app in a couple of hours.

Add to that the incredible flexibility afforded by 3rd party components like DevExpress and you had grids and other tabular components that even today any amount of HTML5, JS and CSS and backend programming could only dream of achieving.

And we did this in the 90s.

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.

If that is the case then one should wonder about the project itself. If the idea and functionality cannot be easily expressed then one wonders whether that project is worth pursuing.

I stopped being interested in the project. I did look at the source and all the magic going on behind the scenes and didn't like what I saw. It reminds of those large frameworks management would buy for big enterprises and say "just use this, this will be really easy, we'll increase the productivity 100%!".

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.

However, then you end up with blog posts like, "here what's new in 3.5", without any documentation for users who never used 3.4 (or 3.3, 3.2...)

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.