[OpenLayers-Users] two different versions of docs

[Bill Thoen]

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