{"id":335,"date":"2008-12-11T16:38:34","date_gmt":"2008-12-11T21:38:34","guid":{"rendered":"http:\/\/crschmidt.net\/blog\/?p=335"},"modified":"2008-12-11T16:38:34","modified_gmt":"2008-12-11T21:38:34","slug":"open-source-project-documentation-openlayers","status":"publish","type":"post","link":"https:\/\/crschmidt.net\/blog\/archives\/335\/open-source-project-documentation-openlayers\/","title":{"rendered":"Open Source Project Documentation: OpenLayers"},"content":{"rendered":"

Earlier today, I read a post on the OpenGeo GeoSpiel blog<\/a> calling for OpenLayers to get on the “Usable Documentation Bandwagon”.<\/p>\n

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<\/a>, 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<\/a>. <\/p>\n

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.<\/p>\n

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.<\/p>\n

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.<\/p>\n

This is exactly the type of reason that OpenLayers is now accepting Sponsorship<\/a> from organizations looking to support the project. This type of improvement is exactly the kind that project sponsorship can help support. <\/p>\n

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<\/a>. 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. <\/p>\n

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<\/a>, 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.<\/p>\n

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.<\/p>\n","protected":false},"excerpt":{"rendered":"

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 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[44,54,18],"tags":[],"class_list":["post-335","post","type-post","status-publish","format-standard","hentry","category-locality-and-space","category-openlayers","category-social"],"_links":{"self":[{"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/posts\/335","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/comments?post=335"}],"version-history":[{"count":0,"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/posts\/335\/revisions"}],"wp:attachment":[{"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/media?parent=335"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/categories?post=335"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/crschmidt.net\/blog\/wp-json\/wp\/v2\/tags?post=335"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}