[OpenLayers-Users] two different versions of docs

Sun Sep 20 12:37:45 EDT 2009

Bill,

Thanks for your detailed, thoughtful, insightful and helpful reply. I
have scanned through it. It merits a detailed response (not for
argumentation, but for contributing back something useful), and I will
do so in due course, but for now, I merely wanted to express in public
my gratitude for you having had three cups of coffee this morning. I
shall be perennially grateful to them beans.

And, the short of it -- yes, I am documenting my experience (OL + MS +
Pg), and will contribute that document back for the benefit of others.
OL is a great piece of work (my compliments to the cooks), horribly
hampered by its documentation. I am not an expert by any stretch of
imagination, but reasonably deft with Perl, SQL and Javascript
(primarily via jQuery nowadays), and I find myself completely lost
most of the times with OL. I hope I can contribute back to correct
that somehow.

Puneet.

On Sun, Sep 20, 2009 at 11:13 AM, Bill Thoen <bthoen at gisnet.com> wrote:
> P Kishor wrote:
>> The only place where the above info is available to me is either the
>> actual source file for WMSGetFeatureInfo, or [2a] or [2b].
>>
>> Once again, I ask, is there some better way, not obvious to me, I
>> could have approached this so as to have an easier time discovering
>> what I could or could not do to construct a proper constructor?
> You'd be a great choice to help put together some documentation written
> by users! What's been written is pretty good, but there's lot that still
> needs writing and organizing.
>
> But to answer your question(s), the differences between similar topics
> are usually due to the fact that one set of documentation is written by
> Natural Docs that scans the  comments in the header and builds a sort of
> Reference Guide, vs. what's written by humans trying to provide a bit of
> a Users Guide, of which is there's not much yet. What's most complete is
> automatically generated and is more of a Users Reference, and there's
> some gaps in that too. The difference being is that the Users guide
> should tell you how to do high-level tasks like how to make a map from A
> to Z, while the Users reference should give you the nuts and bolts
> details about the functions mentioned by the other.
>
> The closest thing to a Users Guide here is the List of Examples at
> http://openlayers.org/dev/examples/ and some of the stuff under "Other
> OpenLayers Documentation" at
> http://trac.openlayers.org/wiki/Documentation, but the Examples need to
> be cross-referenced by the function(s) they demonstrate and hyperlinked
> to the appropriate page(s) of the natural docs. Also a relatively new
> but good set of Users Guide documentation is the "Documentation" page at
> http://docs.openlayers.org/, but that's not as complete yet as I'd like,
> though probably that's one people should read first. All of these can be
> found fairly easily by following the obvious links to "Documentation"
> from the home page.
>
> One area of hermetic knowledge that's often not known to new users is
> the conventions used in building OpenLayers. These are probably so
> second-nature to the developers by now that they don't realize what a
> handicap not knowing these conventions is. In fact, knowing some of
> these conventions obviates the need for documenting what would be
> otherwise a rather long list.
>
> One simple convention that's worth knowing is how the code modules are
> named and organized in the source code library. If you know this one,
> then it's very easy to find the source code files for  any object; just
> change the dots in the object name to forward slashes and that becomes
> the path to the source code file.
>
> Most newbies find that one quickly enough, but a more subtle one is the
> convention used to set displayClass names.  All objects that have a
> displayClass property are set to the value  "ol" + class name + object
> name, without the period delimiters and camelCased. For example
> OpenLayers.Control.Panel would become olConotrolPanel. If it's an object
> like a button that has different states you add ItemActive or
> ItemInactive to the base, as in olControlDragPanItemActive, and if  it's
> an object associated with an action, like a  cursor , you add Active to
> the base, as in  olControlDragPanActive.  This convention may no big
> deal to those who use it all the time, but once you realize it, the
> frustrating problem of no documentation listing all these classes just
> goes away!
>
> Another one is the convention for passing an arbitrary list of
> user-modified properties to an object's constructor. Not understanding
> this one the newcomer can't believe such an obvious gap in the
> documentation exists and  screams for documentation with a question like
> "what are the !@#$% choices that go in the 'options' hashtable
> parameter?" Actually that's fairly hard to document for each class
> object because you'd have to repeat some of the properties over and over
> (because they're inherited), or just write "see list of properties in
> ancestor class.", which is sort what we get told now anyway. But all you
> have to do to generate the list of these properties is to open the
> source code for the function you're calling and note the classes it
> inherits from; which are listed right there in the header after the
> words "Inherits from". Then open that module and see where it inherits
> from, and continue back until you get the original prototype. Finally,
> with that list of classes, go to the Natural Docs pages for each class
> and make a list of all properties from the origin function to the one
> you're calling and that's your list of potential properties for the
> "options" object. Who'd want to document that? Also, 90% of the
> possibilities aren't relevant in any given situation, but knowing this
> convention and what you need, you could easily determine the parameters
> you need for the options without documentation.
>
> Perhaps knowing the conventions of how classes are built in OpenLayers
> would have helped  you to home in on your problem, but I think in this
> case the root of your problem was more of a JavaScript one than an
> OpenLayers one, and then it was further obfuscated by the fact that you
> could specify the map parameter in more than one place, but only one
> combination would actually work.
>
> Finally, I'd like to suggest that if you're perceptive enough to analyze
> the docs this closely that maybe you'd be interested in going just a bit
> further.  I think what's needed to encourage users to contribute
> documentation for things they've discovered that need more explanation
> than what the docs provide now is a framework to provide a place for
> little pieces of documentation. Where people might not want to take the
> time to do something detailed and formal, they, might be willing to do
> short and quickly. This could go in the wiki, linked to the general
> Documentation page and eventually be incorporated in the official
> documentation.
>
> (sorry for writing a novel here this morning, but three cups of coffee
> can cause loggorhea!)
>
> - Bill Thoen
>
> _______________________________________________
> Users mailing list
> Users at openlayers.org
> http://openlayers.org/mailman/listinfo/users
>

-- 
Puneet Kishor http://www.punkish.org
Carbon Model http://carbonmodel.org
Charter Member, Open Source Geospatial Foundation http://www.osgeo.org
Science Commons Fellow, http://sciencecommons.org/about/whoweare/kishor
Nelson Institute, UW-Madison http://www.nelson.wisc.edu
-----------------------------------------------------------------------
Assertions are politics; backing up assertions with evidence is science
=======================================================================
Sent from Madison, WI, United States