I have difficulty understanding the documentation. Is it just me? Are there alternative sources of information?
closed as not constructive by Ian Turton♦, Mapperz♦ Jan 3 '12 at 14:37
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance. If this question can be reworded to fit the rules in the help center, please edit the question.
OpenLayers, as a project, started with a notion of "documentation by example". That is, the primary documentation for many aspects of the code is the almost 200 examples that we make available, with full code to back them. This is typically the first resource to go to for any documentation needs.
After that, we expanded to API documentation. This was an area where we extended later, instead of starting with that as a basis -- this means that it is somewhat less developed, and a bit counter to how most of the OpenLayers developers approach documentation. The API docs are simply less complete because it's not our primary way of communicating about the code.
In order to cope with poor API documentation tools, and the fact that examples simply don't scale to a project as large as OpenLayers, the prose documentation is intended to fill the gap. For the limited coverage it has, it is generally said that the prose documentation is actually quite good, and I'd be surprised if you're saying that this is what sucks. Instead, the problem is that the coverage is quite low -- and the reason for that is simply that limited time on OpenLayers is invested on new features, not on documentation.
While you can argue the approach that OpenLayers uses -- whether it be documentation-by-example, or documentation taking a back seat to actual development -- both of these tend to be simply differences of opinion on what is more important.
Lastly, there are several significant contributors to the OpenLayers project who work primarily on funded projects from contract development. Both of these teams have made offers to groups to accept funding for development of documentation. Most features in OpenLayers are developed this way, but documentation has not been successfully developed this way, due to lack of appropriate funding. In short, it seems that no matter how much people dislike the documentation, they don't want to pony up the resources to improve it.
Well you could argue that its both you and the documentation. Since I only know the documentation, I'll prefer to discuss that :)
In my opinion the documentation doesn't give enough information. Thus I read the documentation and browse through the source code alongside to give me a better picture of how things are working.
Though the documentation could be more thorough, a lot of examples are available and google gives you even more.
The OpenLayers guys maintain a mailing list, though I think this forum is much more usable than browsing through lots of mails :)
So, if you have any questions, just ask here - but I would suggest that you phrase your questions a bit more positive ;)
I'm not sure where your abilities are, but Packt Publishing has a book. I've never used it and haven't read reviews on it, but it may be worth purchasing. The E-Book is the cheaper option.