Re: [Geotools-devel] Geotools user documentation

[Cameron S. <ca...@sh...>]

On Monday 01 Mar 2004 9:55 am, Rueben Schulz wrote:

> 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.

Yes, you are right.  Since we don't have a Users Guide yet, the Design has 
some Users Guide information in it.
It would be great to build a Users Guide and do some refactoring of the Design 
doc.


> When I started learning geotools last year, I found the
> design document very useful 

I'm glad at least one person found this useful.  This document could also do 
with updating.  In particular, it would be great to update the UML diagrams 
(which were created with Poseidon).

> 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.

Yes.  The documentation is written in docbook.  Using modular docbook you can 
include the same "System Overview" in both the Design and Users Guide.

>
> 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.

Yes.

>
> 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.

Yes.

If you are offering to do the writing, I'm prepared to answer any technical 
questions about writing docbook.  (There is also a section on it in the 
Developers Guide).

PS, if you want a fast response, it is best to email be direct and CC the 
list.

-- 
Cameron Shorter