Need more documentation

Martin Desruisseaux added a comment - 23/Feb/06 5:04 AM I realize that the lack of documentation is a very serious problem. This is an area where contributions from users would be really appreciated. Some Geotools developpers are unfortunatly trapped in very thigh schedule. On my side I urgently need a GO-1 implementation for a software. Our funder don't care about geotools - he just wants the application. Today, I worked 12 hours on GeoAPI (which is related to Geotools) and answering emails on the Geotools mailing list, and it was an ordinary day. While a fully agree that writting a good documentation is critical, it is sadly impossible for me at this time. I believe that in order to get this job done, we need to raise money in order to paid somebody. Many open source project with good documentation hired somebody for writting it. Maybe this is the kind of task where the OSGEO foundation ( http://logs.qgis.org/geofoundation/ ) could help - I don't know. Nevertheless, this permanent rush should not be an excuse for poor code in the Geotools SVN. Code quality in Geotools is variable. Worst, some modules have no maintainer and there is no warning to users about that. This bring us again to a similar problem than the documentation. Nobody is paid for maintaining Geotools - every developpers are busy in solving their own problems. Maybe Geotools has reached a level of complexity where we need someone dedicaced in maintaining and documenting it. It can be a full time job, and I have no idea where we could find funds for that. On the bright side, at least for some of the modules I'm involved in (referencing, coverage, go), the OGC specifications can be used as a documentation. For example users can get a general idea about the referencing module in the ISO 19111 specification, which is freely downloadable from the OGC web site.

Chris Holmes added a comment - 23/Feb/06 10:42 AM Yes, the hope with osgeo is that organizations can 'sponser' GeoTools, and some portion of overhead goes to the foundation, and the rest goes to fund exactly things like this, documentation and code maintenance, the less glamorous things that the core developers never really get paid for, since just like Martin, our funders all want applications.

Jody Garnett added a comment - 28/Feb/06 11:52 AM I am currently herding the stable apis into module/api and will start to document them. The developers guide is kind of working now after all ;-) My check list before things are worth documenting is 1) feature model update from geoapi 2) consistent use of interface/factory ... so we are getting closer.

Jody Garnett added a comment - 05/Mar/06 3:46 PM I am assigning this bug to me so I can watch it, in all likely hood this bug will need to develop sub tasks and have a bit of a plan. I will mark it down for the 2.3 timeline. I don't find 2.2 to be stable enough to be worth documenting. By starting early on 2.3, with documentation as a driving force I hope to settle the code base. That said some area of 2.2 are stable and we can explore that with subtasks. That said I am sorry I need to mark this back to Critical (prevents release) against 2.3. We simply have too many other things requiring 2.2, and this item is does not block geotools - it is just very unhelpful with respect to the project being a success or recruiting new volunteers.

Jody Garnett added a comment - 18/Apr/06 8:11 AM We are actually getting some progress here, the last IRC meeting provided a strong mandate to fix this before geotools finishes the OSGEO iccubation process. And we are actually going to do that by "Need less documentation". The idea is to focus on what we need to document, and figure out how that can be kept up to date. Much of the documentaiton we do write is usefull for the developer community (background, specifications, and so on), but is off topic when we focus on documenting the toolkit as a whole. Please see this page for a fist draft of requirements, I will argue hard against adding anything more until I see that the community can accomplish even this much. - http://docs.codehaus.org/display/GEOTOOLS/Fix+the+Docs

Adrian Custer added a comment - 29/Nov/06 8:13 AM bump the fix version since all my doc work is on trunk --adrian

Jody Garnett added a comment - 10/Jul/07 12:15 PM Marking this as fixed: We have set up an entire wiki for user level documentation. - http://docs.codehaus.org/display/GEOTDOC/Home The document is structured as a reference - against each geotools module. While not the best for an introduction it does offer something important. It is a style of documentation that strongly associates a module maintainer with the documentation they need to provide (in order for their module to be considered supported). WELCOME / INTRO MATERIAL There is a section for "Welcome" documentation - and we are going to ask that any code examples here are backed by code in the "demo" folder. ADVANCED TOPICS AND FORMAL GUIDES For some modules more is needed - particular for modules that support user added functionality via a plugin system. These modules will require a formal "guide" be provided - mostly containing design documentation targeted at a plugin implementor.

Jody Garnett added a comment - 10/Jul/07 12:17 PM This page will be updated to reflect the documentation policy: - http://docs.codehaus.org/display/GEOT/3.4+Confluence