Brill Pappin wrote on 02/23/2006 02:30:36 AM:
> Need more documentation > ----------------------- > > Key: GEOT-812 > URL: http://jira.codehaus.org/browse/GEOT-812 > Project: GeoTools > Type: Improvement > > Versions: 2.2-RC0 > Reporter: Brill Pappin > Priority: Blocker > > > The GeoTools API is an extreamly complex one but there is very > little documentation. While I realize that this is a project made up > of volunteers, using and/or improving it it next to impossible. > > I would like to request that the team implement a code freeze and > spend some time updating the documentation adn examples. > There are also several places where the code in incomplete and some > time spent finishing up those points would be helpful. This is highly unlikely: let me explain why. GeoTools is based on an entire family of standards which are interrelated. Worse, there are two issuing standards bodies: OGC and ISO. OGC seems to be at the bleeding edge: one may consider standards from them to be of a "beta" quality, less specific/constrained/integrated than ISO, but with more new features. After incubating in the OGC for a revision or two, many standards "graduate" to ISO, which applies some lessons learned. More importantly, ISO attempts to integrate each standard into the family such that re-use is maximized and each standard encapsulates a well-defined problem domain in a way that it too can be re-used. Nothing illustrates this more clearly to me than the difference between OGC Coverage and ISO Coverage specifications. Why is this bad? Well, to do anything really useful (like serve web pages with maps) the defining standard upon which one relies (and therefore the code one uses) depends on a large body of "building-block" standards (code). These building blocks depend on other standards, etc. At the core is a set of at least six standards which are basically inbred. So to start, one must become familiar with these six standards roughly simultaneously, then build upon that knowledge in order to do anything cool. Exactly the same statement could be made about the code one uses, since it is roughly partitioned along the lines of the various standards. The essential problem is that no set of demo code snippets could possibly be construed as a substitute for this basic knowledge. The GeoTools learning curve is steeper than this, not because the code is convoluted (yes, in some places it is), but because the concepts represented by the code have a fair degree of complexity to them. If one learns the concepts from some external source, it has been my experience that mapping them onto the GeoTools code base is a relatively trivial matter. However, learning the same concepts from the Javadocs never seems to work out quite so well for me. So for me, Hard Part: concepts Easy Part: mapping to GeoTools (or noticing a void) This implies to me that what is needed is "Geospatial Technology In a Nutshell" by O'Reilly. It doesn't even have to cover GeoTools specifically. However, if you're interested in plunging into a specific area to learn concepts, write code, or document an existing mapping from concept to code, this list is a really good resource! No matter what topic you choose, the first step is likely to be to locate the relevant standard and try to learn it. This process may involve looking up other standards until you're sick of it. When you start to develop questions, this list is likely to reach someone who has an intimate familiarity with the particular problem domain you're interested in. Sorry about this, once I get going there's no stopping me. :) Bryce ------------------------------------------------------- This SF.Net email is sponsored by xPML, a groundbreaking scripting language that extends applications into web and mobile media. Attend the live webcast and join the prime developer group breaking into this new coding territory! http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642 _______________________________________________ Geotools-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geotools-devel
