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.

  • 4
    flagged: rant diguised as question – unicoletti Jan 3 '12 at 8:00
  • 1
    edit note: severe editing of a poor question, but the answers thus far are very interesting. – djq Jan 3 '12 at 13:04
  • 1
    I'd try: How can we make OpenLayers documentation even better? – Kirk Kuykendall Jan 3 '12 at 15:22
  • To all: In light of the preceding comments and the many views and votes the replies have been getting, I have attempted to reformulate the question constructively. If you agree the question is now tenable (or that the replies deserve to be made visible to all) and have sufficient reputation, you can express your interest with a vote to reopen. If you don't have the reputation, you can still easily express your view by upvoting the question itself if you like. (As a mod, I am reluctant to unilaterally reverse a previous action.) – whuber Jan 3 '12 at 23:49

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.

  • Roughly speaking, how much funding would be required to resolve the documentation issues? – dassouki Jan 3 '12 at 13:01

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

  • 1
    For the record, very few OpenLayers developers use stackoverflow compared to the number of users and developers who are available on the mailing list. In general, I see the same dozen people on Stack overflow -- but the OpenLayers mailing lists have more than 1000 people signed up to them. So, SO isn't always your best option to get correct answers quickly. – Christopher Schmidt Jan 3 '12 at 12:48
  • 4
    I know, I subscribe :) But I prefer the way SO categorises and visualises questions and answers. The amount of mails indeed supports your statement, but its like a stack of unsorted papers - very difficult to grasp. I think it would be great and much more useful to have the system SO uses instead of the mailing list - but thats my personal opinion. – Chau Jan 3 '12 at 13:53
  • 4
    Maybe you could persuade some of the those mailing list members to become active here, Chau :-). – whuber Jan 3 '12 at 16:11
  • I think that persuasion should come from the knowledged ones answering their mailing list questions. If they don't want to use this forum and thus refer people here, why should the askers go here? Then my personal preference doesn't matter ;) – Chau Jan 4 '12 at 13:01

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.

Not the answer you're looking for? Browse other questions tagged or ask your own question.