Open Source Project Documentation: OpenLayers
Earlier today, I read a post on the OpenGeo GeoSpiel blog calling for OpenLayers to get on the “Usable Documentation Bandwagon”.
Now, I’ll be honest: I followed the links that he offered, and found something that is not, to me, much more convincing than the OpenLayers documentation as it stands today. If I look at ESRI’s JSAPI, I see a couple things wrong right off the bat — like the fact that I can’t actually link to where I want to. In any case, if you click Geometry -> Point, you see a document which, to me, is a lot less interesting than the similar page provided by OpenLayers.
Perhaps there is some subset of documentation put together by ESRI in their JSAPI that makes sense, but for an API reference, it seems to me that OpenLayers does reasonably well on the portions of our API that someone has invested time to work on.
This doesn’t mean we’re “done” by any stretch of the imagination: One of the things that I’ve wanted to do for ages is actually sit down and do a thorough review of the OpenLayers API documentation and improve a lot of it, targeting cross-linking with other documentation and examples especially. These types of tasks, however, are the types of tasks that require a lot of time, and don’t have a lot of immediate benefit. Since all work on OpenLayers for the past several months has been my personal free time after work, there’s only so much I’m personally able to do. However, no one has *ever* made a request to the OpenLayers team to be able to do this work — including OpenGeo — that I’ve seen. It seems to me that whit is experienced and knowledgable about OpenLayers, since I’ve seen him using it for development, but I’ve never seen him ask to participate in improving the OpenLayers API documentation on the mailing lists, nor have I seen a request of this nature from any other organization.
To me, this means that it’s likely that our API documentation does, to some extent, meet the needs of the organizations using OpenLayers. It’s not perfect — nothing is — but no one thinks it’s a major stumbling block that’s worth fixing, at least not enough to spend money on it.
This is exactly the type of reason that OpenLayers is now accepting Sponsorship from organizations looking to support the project. This type of improvement is exactly the kind that project sponsorship can help support.
OpenLayers is aware of how important documentation is to the success of the project. We have invested dozens of hours between a dozen different contributors to create and maintain a set of relatively complete API documentation. According to Ohloh, of the 55,000 lines in OpenLayers Javascript, over 30% are comments: over 25,000 lines of what is mostly API documentation. No one is ignoring the problem — and if the current state is insufficient (as everything in the project is, *especially* to new users and beginners), then we’re very open to help from any and all interested parties.
API documentation isn’t the only thing a project needs, of course. Documentation comes in all forms — and OpenLayers is seriously lacking in a lot of documentation targeted towards beginners of all kinds. We’ve been working to change that, with a new documentation site available, and other efforts targeted documentation of OpenLayers in English and other languages. I would say these efforts are much less complete than the API documentation, and starting on them is far more important, in my opinion, than improving our API documentation is at this time.
OpenLayers is a large library. It’s used by many organizations. We’re open to contributions of all types — never have I seen OpenLayers turn away someone who wanted to help with documentation intentionally. We have regularly worked with contributors in helping them to improve the documentation, and to claim that we are ignoring the need for documentation seems to me to be representative of a lack of knowledge of the tools that the project uses for documentation, not specifically a lack in the goals of the project, which puts documentation of functionality — via API docs and minimal examples demonstrating functionality — as a requirement of almost all new code in the library.
December 11th, 2008 at 7:22 pm
[…] this post prompted some possible deserved ire from chris schmidt on his blog. More importantly it included a link to the new openlayers docs […]
December 11th, 2008 at 7:55 pm
[…] last post prompted some possibly deserved ire from chris schmidt on his blog. More importantly it included a link to the new openlayers docs site. Linking this […]
December 11th, 2008 at 11:24 pm
Hi Chris,
I think what OpenLayers lacks the most is a document that goes over the design concepts behind OpenLayers components like controls, panels, handlers etc. Like if I wanted to create a custom layer class OpenLayers what are the steps to do so and simpler things like what CSS styles will be applied to toolbar items in various states by default are also not documented anywhere that I could find. If there were some sample walk throughs that go over how to some simple tools that use the mouse and key board handlers would be amazingly useful. I would be willing to contribute to some of that samples and walk throughs if there is somebody I can ping and get help and clarifications.
Thank You,
Vish
December 12th, 2008 at 8:30 am
Personally, I think the issue with api documentation of any kind is that it’s intimidating to the beginner. It’s a bit of a catch22 scenario that you have to know a bit about how javascript works to understand the documentation, yet if you’re anything like me you are probably looking at the documentation to try and learn how to do something you’re stuck on! Having said that, as I (slowly) come to understand how openlayers and javascript work I really appreciate the api and the sets of examples. Would it be possible to see more integration between the two- ie links from the examples page to the api docs, and vice versa?
December 12th, 2008 at 11:08 am
Aracheogeek/Vish:
I agree that the existing OpenLayers documentation for beginners is poor. Part of this is that the *language* documentation is terrible: there is nothing even close to resembling a good Javascript reference guide, so most users are trying to learn two things at once from the OpenLayers docs — Javascript, *and* OpenLayers. This is a pretty crappy problem for a project like OpenLayers to try to be solving, but I agree that at least some beginner tutorialing in this regard would help.
That said, I’m definitely of the opinion that OpenLayers could use more prose documentation of the beginner sort. Some of this is actually improved significantly by the intro-to-openlayers workshop that OpenGeo put together:
English | French
This material provides a good starting point for working with OpenLayers for the first time, and provides some really useful overview. I appreciate that OpenGeo put it together, though I am finding myself frustrated by the number of people who have put together documentation, then put no effort into bringing it back to the OpenLayers community directly.
There is obviously much more to do in this regard: the OpenGeo workshop is great as a workshop, but doesn’t translate as nicely into setting up your own as it could, and we obviously have a lot more functionality in OpenLayers to document.
There seems to be a statement drawn by the post from whit: “OpenLayers has bad docs because developers don’t know that good docs are important.” Good docs are extremely important. OpenLayers, as a project, has invested probably more than 100 man-hours in docs. (I know that I’ve invested 30+ on my own — I spent a whole weekend doing the natural docs conversion, and I was far from alone.) Yes, they’re still insufficient, and yes, they could use more work — but that doesn’t mean we’re ignoring them. These things are hard to solve, and require a major investment. No one — no organization, no individual, no team of people — has made a major investment in OpenLayers docs, and until they do, things will continue to be the way they are.
Some organizations have put forth a number of minor investments: it’s my goal to get these things integrated into OpenLayers documentation, but I’ve not seen anyone else in the core community express interest in it. Even OpenGeo didn’t offer a helping hand in making this happen — despite clearly investing in their OpenLayers workshop, it took more than a month before I had the chance to propose tighter integration into the OpenLayers website, and still received no assistance from anyone other than myself. This says to me that — to some extent — these organizations are not “investing in OpenLayers” in this way, but are simply investing in themselves. This is a fair choice — no organization can take on OpenLayers as their own requirements — but to ignore the efforts of people who *are* investing in it in the way that the post did was frustrating to see.
December 12th, 2008 at 11:26 am
Vish,
To more directly address your question regarding getting help working on docs: I’m always available on IRC to answer questions, and especially if you tell me you’re writing docs, I’m very helpful/friendly 🙂
December 12th, 2008 at 6:26 pm
Personally, I have been very impressed by the OL docs. I like it much better than YUI api docs, Google maps API docs, and many other both open source and proprietary javascript libraries that I have seen. I really appreciate the strict inclusion of proper API documentation and tests for any new components that are accepted into OpenLayers.
When you combine the documentation with the vast number of functional, tightly focused examples, one can gain a very deep understanding of OpenLayers quite quickly.
The main pre-requisite to getting the benifit of these examples and documentation is a good understanding of object-oriented javascript programing.
Thanks to you Christopher and to all the other OpenLayers PSC members and commiters.
December 13th, 2008 at 9:18 am
I would like to see a pdf file of some sort. So it could be moved to a closed network that does not have internet access. Is this already available. Specifically the developer docmentation.
December 13th, 2008 at 9:54 am
Tia:
The OpenLayers Developer Documentation (API docs) do not require network access. Each release of OpenLayers is provided in two forms: with and without documentation. The with documentation build is much larger (about twice as large), but includes pre-built versions of all documentation, in the ‘doc’ directory. These are available from the OpenLayers Download Page.
It still requires a web browser, but the documentation is fully usable offline.
At this time, our API documentation is generated by NaturalDocs, which has no PDF generation option. Because of the way the code works, I’m somewhat skeptical that it will be added at any point in the near future. However, if the goal is just “viewing offline”, I think our existing documentation works okay.
Does this solve your problem?
December 13th, 2008 at 6:52 pm
ah I downloaded the wrong one rats