On Aug 9, 2011, at 3:57 AM, ext Marc Jansen wrote: > Hi Eric, > > good to bring this topic up again! > > > On 09.08.2011 09:45, Eric Lemoine wrote: >> Hi >> >> Some of us among the OpenLayers devs have been contemplating the idea >> of offering a better API documentation for OpenLayers. > > I'd count myself to those devs. And from the first feedback about common > pitfalls/annoyances of OpenLayers I see that many users do not like our > current documentation.
While I'd love to see better API Documentation, I despair of ever finding tools that do it sufficiently. My recent perusal of the various competitors to OpenLayers in documentation basically came to the conclusion that there are two options: tons of manual labor, or bad docs :) But I'm happy to go with whatever people want to do for it -- I don't think that any of the tools are likely to lose us what we already have with NaturalDocs. That said, In my experience, what people want is not better API docs (which probably won't help a ton), but more concrete usage demonstrations -- expanded content like http://docs.openlayers.org/library/introduction.html to cover the entire library. In looking at the things that people said they liked better, that was pretty much the clear indication that people would like documentation the most: thorough and complete walkthrough-style examples of as many parts of the library as possible. http://crschmidt.net/blog/archives/472/perceived-flaws-ofopenlayers/ has the results of what I looked through, which examined 5 different web mapping libraries stated to be alternatives to OpenLayers, and what documentation they offer. >> With this email >> I'd like to gather comments, opinions, and ideas regarding the current >> API documentation, and what we should do to improve it. >> >> I've been looking at JsDoc lately. (Yes, I know we moved from JsDoc to >> NaturalDocs 4 years ago! [1]) Using JsDoc annotations would provide us >> with two things: (1) generate a nice API documentation using JsDoc >> Toolkit [2], and (2) fully benefit from the Google Closure compiler >> (code optimization, type checking, warnings, etc) [3]. What I also >> find interesting about JsDoc is that it is a standard for annotating >> JavaScript code; other tools, like dox [4], support it. >> >> Any comment or experience is welcome! Thank you. > > We have worked with JsDoc and liked it. What about the usual suspect > Sphinx? And an output equivalent to the one of GeoExt? The Sphinx stuff inside of the GeoExt library looks a bit more like line noise than I'd personally prefer, and I'm not sure how much benefit the GeoExt docs offer over the NaturalDocs we have; I think the complaint with OpenLayers is less about how the docs look, and more about what the docs *are*. I'm willing to adjust that notion (even without evidence; it's not a strong conviction), but I think that sphinx would be a major change, and I'm not sure how much it would help? Although, it would let us better integrate our API docs with the rest of our docs -- for that reason alone, it's almost certainly worth considering. I think tighter integration between reference docs and prose documentation is absolutely neccesary to help improve the perception of the documentation in OpenLayers. -- Chris >> [1] >> <http://osgeo-org.1803224.n2.nabble.com/finally-fed-up-with-jsdoc-td1833145.html> >> [2] <http://code.google.com/p/jsdoc-toolkit/> >> [3] <http://code.google.com/closure/compiler/docs/js-for-compiler.html> >> [4] <https://github.com/visionmedia/dox> >> >> PS: I'm interested to work on that at the FOSS4G code sprint. >> > I am also interested in this particular topic and would gladly help at > the FOSS4G codesprint. > > Best regards, > Marc > > _______________________________________________ > Dev mailing list > d...@lists.osgeo.org > http://lists.osgeo.org/mailman/listinfo/openlayers-dev _______________________________________________ Dev mailing list d...@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/openlayers-dev
