Details

    • Type: Improvement Improvement
    • Status: Closed Closed
    • Priority: Critical Critical
    • Resolution: Fixed
    • Affects Version/s: 2.2-RC0
    • Fix Version/s: 2.4-RC0
    • Component/s: docs
    • Labels:
      None

      Description

      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.

        Activity

        Hide
        Martin Desruisseaux added a comment -
        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.
        Show
        Martin Desruisseaux added a comment - 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.
        Hide
        Chris Holmes added a comment -
        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.
        Show
        Chris Holmes added a comment - 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.
        Hide
        Jody Garnett added a comment -
        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.
        Show
        Jody Garnett added a comment - 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.
        Hide
        Jody Garnett added a comment -
        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.
        Show
        Jody Garnett added a comment - 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.
        Hide
        Jody Garnett added a comment -
        Assigned this to the website component, and marked this as a critical bug for the 2.3 release.

        You will find that documentation in general is a community effort, and the developers guide is an excelent resource.
        Show
        Jody Garnett added a comment - Assigned this to the website component, and marked this as a critical bug for the 2.3 release. You will find that documentation in general is a community effort, and the developers guide is an excelent resource.
        Hide
        Jody Garnett added a comment -
        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
        Show
        Jody Garnett added a comment - 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
        Hide
        Adrian Custer added a comment -
        bump the fix version since all my doc work is on trunk --adrian
        Show
        Adrian Custer added a comment - bump the fix version since all my doc work is on trunk --adrian
        Hide
        Jody Garnett added a comment -
        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.
        Show
        Jody Garnett added a comment - 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.
        Hide
        Jody Garnett added a comment -
        This page will be updated to reflect the documentation policy:
        - http://docs.codehaus.org/display/GEOT/3.4+Confluence
        Show
        Jody Garnett added a comment - This page will be updated to reflect the documentation policy: - http://docs.codehaus.org/display/GEOT/3.4+Confluence

          People

          • Assignee:
            Jody Garnett
            Reporter:
            Brill Pappin
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: