[Geotools-devel] Geotools user documentation

[Rueben S. <r_j...@ya...>]

To All,

The following is a list of some things I would like to see on the
geotools web site. Note that I will not have any time to work on this
until May, but I wanted to put this up for discussion now (go ahead,
shoot me down, I can take it).

We all know that documentation is hard for developers to do. However, as
a geotools user it is very important and currently lacking (yes I know
there has not been a formal release yet).

What I propose is a section on the right side of the site titled "User
Information". Preferably this would be immediately after the "Developer
Information" section. This would contain a link to the tutorials (on
their own page) and an overview document about what geotools can do.

I think the tutorial should be on their own page, since I am optimistic
and hope that there will be lots of them in the future (soon).

I think an overview document is necessary, because I cannot figure out
what geotools does based on the info currently on the site (am I missing
something?). When I started learning geotools last year, I found the
design document very useful (for example I had no idea what sld was
then). This document is currently in
geotools2/geotools-src/docs/sdocbook/design.xml. I think that a short
version of this would be useful for new users. This would give a
description the major modules in geotools so people know what it can do
and which OGC specs are being implemented (a feature list). A list of
supported data types would also be good. Last I looked, I think I needed
more than two hands to count them all - amazing. 

I see two problems with this:

1) there is an overlap between user and developer documents so it is
hard to make a distinction between them. The tutorials are useful to
both groups of people.

2) anything written is quickly out of date. But I think this is true of
any documentation, so they will need to be updated every few months.

Apologies if this was already discussed on a irc that I have not read.

Rueben