[Geotools-devel] The status of docs in uDig [was: Info view oddities]

[Adrian C. <ac...@gm...>]

Hello all,

This is a status document for the documentation stack of uDig. I've
spammed the other lists for anyone searching the archives. Please
respond on udig-devel list.

On Tue, 2007-05-29 at 15:50 -0400, Peter N. Schweitzer wrote:
> But like this list, "udig-devel@...", I'll point out that the wiki
> appears (to me) to be the only place to build documentation that
> can help people use the software.  If there's another, better place
> for this information, point it out.

Hello,

You seem to have the same intent as many of us, notably "I don't know
what's going on, if i figure it out I'd sure like to share." I'm glad
you share that intent. So now, how do we get your energy firing
productively?

Since, there are two kind of uDig users, program users and extendors,
I'll presume you are interested in the second since "how to use uDig" is
kindda simple and not terribly interesting given the current state of
uDig. So if we want to help others learn to code uDig then we have a
real, long complex task. 

Here's a synopsis of the state of affairs:

        To understand uDig, a user needs to understand Programming
        (subversion, Eclipse IDE, design patterns), Java (logging,
        beans, maven), GeoAPI, Geotools, and Eclipse RCP. 
        
        Since uDig relies on Geotools/GeoAPI that's the place to start.
        Geotools is so close to moving to GeoAPI based geometries and
        *everything* rests on geometries, it's a pity to launch into
        user docs for that prior to that transition. Ibid for several
        other areas of Geotools. 
        
        The quick state of Geotools from a document perspective:
        
        Geom
                currently JTS which itself has good docs.
        Metadata
                currently read only, makes writing docs painful
        Referencing
                kick ass, but very complex geometrically, relies on geom
                which is moving to GeoAPI so may make sense to wait
        Filter
                that could use a systematic document, there's a bunch of
                info on the wiki
        Feature
                about to change from simple to complex, perhaps worth
                waiting
        the rest
                in various states of stability
        
        
        of uDig:
                Essentially no docs for mortals, some docs for
                programmers who understand eclipse and complex 'design
                patterns', and no javadocs in the code base. uDig is
                hard to understand let alone document. Currently the
                code and docs are only useful to those who already
                understand Geotools and Eclipse and speak the lingo of
                modern coders. 
        
        of Docs:
                Geotools has four documentation efforts:
                        The wiki
                        The developer's Guide
                        GEOTDOC wiki space --- a user guide for
                        programmers
                        The doc/ directory --- a user guide for
                        non-programmers
                        
                uDig has various documentation efforts:
                        Some 'how to use uDig' docs
                        Minimal javadocs
                        Some snippets and other docs for programmers

So in that framework, you need to decide how you can contribute.

If you want to focus on uDig, I would urge you to focus on the javadocs
as you figure things out. Pick an area you want to pursue, figure it out
and write up what you understand in the javadocs.

I just tried to fix a bug in the database connection system---that
became a three week effort of decipher, re-write and compose javadocs.

It seems that the core uDig folk don't (or didn't) have a mandate to add
javadoc which makes uDig code very difficult to navigate. The result is
that all the components of uDig will have to be re-edited possibly
re-written. 

I've come to think of uDig evolution in terms of waves. The first wave
(current) is by hard core coders who understand Eclipse and give us a
working system. The second wave (future) cleans up and documents the
code. A third wave will refactor things to improve the user/programmer
experience. 

So, both Geotools an uDig are *very* young projects that have chewed off
a big chunk and have a long way to go to be easy to use and extend.

Hope that helps you think about things and glad you are inspired to
contribute,
--adrian