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.