Hacker News Reader

Comment by alxndr | Hacker News Reader

With this many people saying the documentation could be improved, is there a reason holding everyone back from contributing or improving it?

View on HN

The irony is that not only is there a commenting system to complain about the docs, but that at the top of most of the pages is a prominent "Improve this doc" button, which when clicked, takes you directly to the file in Github. Some of the docs are .md (markdown) while the rest are the actual code files. I don't know how often they accept pull requests, much less for doc-only changes, but they have almost 150 PR's in queue.

And this is something I was unaware of until now, a "Contributor License Agreement"[1] is required for a pull-request to be accepted. Sheesh, that's kind of a PITA...

1. http://docs.angularjs.org/misc/contribute#CLA

It was a while ago when I last did it, but the team are perfectly happy to merge-in docs corrections and improvements. IIRC, the CLA is not necessary for docs either, only for actual code.

At the last London AngularJS meetup it was mentioned that the team have 'pull request parties' where they try to merge or close as many contributions as they can, but more of them just keep coming ... good problem to have I guess, but they are aware of it and trying to address it.

In my case it's because I don't understand it well enough to write doc. The people who _do_ understand it well have managed to do so despite the state of the documentation, so maybe they think the doc is sufficient?

It's one of those nasty problems, like the influence of money on politics, or gerrymandering, where the people best able to fix it are the ones least likely to think it's a problem.

A lot of us have invested a lot of time learning Angular, pains and all :) . I've contributed to the docs, as well as source. I've also reported issues, big and small.

The current docs have come a long way from their previous state - I recommend people try taking a look at them now. The developer guide & API docs have gotten huge improvements within the past month! I think the only things that are really left is to recommend some best practices with examples and more examples in the API section.

The barrier of having to contribute via GitHub is actually a fairly large one. Think about it; not even all developers understand git. The design challenge of creating a simple way to contribute/improve documentation (read: educational materials) is something we're working at Coursefork [1]. It's a tough one to solve, but we think we've cracked it.

[1]: http://coursefork.org

/shameless plug

Reply on news.ycombinator.com