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, "[EMAIL PROTECTED]", 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
-------------------------------------------------------------------------
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
