How can we improve the OpenLayers documentation? [closed]

Question

I have difficulty understanding the documentation. Is it just me? Are there alternative sources of information?

Answer 1

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.

However, this particular problem is not helped by the fact that JavaScript API documentation for a project like OpenLayers is extremely difficult to make easily available and accessible due to poor tools. The JavaScript language doesn't actually have many of the constructs that OpenLayers uses at its core -- like the class inheritance structure -- as first order objects, which means that they are tacked on, and documentation tools don't have universal support for them. So, the lack of language support or any sane tools to do documentation play a role. (This situation has improved over the years, but it's worth noting that OpenLayers -- and the source of its documentation and tools -- is older than many JavaScript projects that exist today, having started 5.5 years ago.)

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.

Answer 2

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.

And if eventually that is not enough, you can use this forum or even stackoverflow to get answers from some of the most experienced people.

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 ;)

Answer 3

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.