Justin Deoliveira wrote: > First off we have three wikis which i can infer are broken up like follows: > > GEOTDOC: User Guide > GEOT: Developers Guide > GEOTOOLS: The front end to both of the above > > Which I guess is not that confusing now that I have just figured it out :). > You got it. > However I am a bit concerned about the content of the users guide. Now > this is just my opinion but its *way* to verbose, in many places it > looks like a design document (talking about interface vs implementation, > bit architecture diagrams, etc...). > It is more of a reference, intro material is in the welcome section. > I think it would be way more effective if it was to the point and just a > series of examples, basically a howto list: > We can add a section for "how to" ... but I want to keep the reference format in order to document the modules. One thing that is important is the separation between the API (gt2-api, JTS and GeoAPI) and the implementation. We are documenting the implementation; and mentioning the interfaces as they come up. > * How to reproject from one crs to another > * How to read a shapefile > * How to parse a gml document > > And the list goes on. Basically just a series of examples well organized > into categories. > We can make a chapter for examples, but really I would like to see the examples *as code* in the demo folder. > Perhaps I am beating a dead horse here but I think on of the problem may > be that the "User Guide" actually cators to two groups of users: > > * Those who want to do something quick and dirty > Everytime I tried to explain in isolation I failed. I need to break it out by module, and show the dependencies or explanations go sideways. Could we have an Examples section for each module? Or one for the entire guide? > * Those who want to do some advanced programming against geotools apis > (like implement a datastore) > That is what the advanced section is ... such as your XML Developers Guide > Perhaps the second should be grouped into a "Programmers Guide". > I think that is already done. > Anyways sorry if this brings your initial thread off topic Adrian, its > more just a rant I have been meaning to do for a while. And I know this > is not anything new as people (such as yourself) i believe think along a > similar line. Its just that with this round of feature model work i will > have an opportunity to do a good chunk of documentation so I would like > to do it right. > Cool. Jody
------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Geotools-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geotools-devel
