I'm in about the same boat as Ian ... I just don't update from trunk until I need to commit. I really do like the idea of point 1 ... but this is alot of work too (practicality kicks in). I would be inclined to help / push point one, but only if we points 4 and 5 are also incorporated. I really do like the idea of keeping a fairly constant API. We end up costing ourselves potential users due to our frequent api changes, but we also cost our current users in terms of developement cycles to update the interfaces.
I am a fan of creating / adopting a set of interfaces ... and with that a (relatively) formal change request method for the associated interface definition changes. With the speed (and ease) of API changes, tasks 2,3 are nearly imposible. I think we should take a look back, and re-evaluate whether this many changes are necessary, and for those that are, what process(s) we want to apply. I realize we currently have a code review process ... but we never get the actual proposed changes written in an email, as simple english.
My preference for API changes is to see a list of additions (in english), a list of subtractions (english) and a prototype (java). This would allow people to ask pointed question about new methods, breaking backwards compatibility, and ease of use (consequently ... people would have to think of these themselves, and hopefully explain then in the english sections). This process would ensure adequate documentation for the javadoc comment, as the discussion ensued should provide either examples or descriptions that can be copied from the email into the javadocs (developer bonus here).
A few of my thoughts ...
David
On 9/27/05, Matthias Basler <[EMAIL PROTECTED]> wrote:
Hi developers,
I took from yesterday's IRC that there had been a discussion about the
documentation and user/developer distinction and the question why lots of
projects like uDig do not "use" Geotools as intended (or develop on the
GeoTools codebase) but just take some bits of it and replace the rest with own
code - and I can include myself here as well.
I've though a lot about where I believe the problems are and how to help. Here
is what I've concluded:
1. Documentation and release policy
-----------------------------------
I believe what GeoTools lacks is a strict policy that states that a dot release
(such as 2.1, 2.2.) can only be released if it is ensures that all code to be
released is documented
- in JavaDoc (and I do NOT mean just placeholder stubs as often in uDig...)
- in a/the tutorial and the code snippets
The ideal solution would be:
1. A Beta goes out - API freeze
2. After this only bug fixing, JavaDoc writing and documentation writing
(plus localization/installer updates in uDig case) are done
3. Release candidates when all three are done
Checking of integrity (and additionally in uDig case testing
the localization, installation procedures etc.)
3. Final x.x release all this three are done.
I know that several people have tight deadlines (see point 4), but the above
strict policy would avoid lots of problems, from my experience. So I believe
it's worth it.
2. Up to date tutorials
-----------------------
There was the idea yesterday (I believe by James?) that for each dot release the
state of the tutorial should be frozen. This goes hand in hand with point 1:
Just before the release and AFTER the tutorials have been updated to reflect
the latest changes, a snapshot is done, ideally converted to some nice PDF "all
in one" tutorial/manual and added to the release.
Any updates then go into the documentation "trunk", whereas the snapshot for the
last official release should be separatly available to the users as the "current
offical version".
Especially in the case of GeoTools - a quickly changing API - I consider it
absolutely vital to have both a "stable release" and a "stable release
documentation", both of which stay up to date (from a user's point) until the
next official release is done.
3. Presentation of tutorials and code snippets
----------------------------------------------
In the meantime the tutorials / code snippets section contains lots of pieces of
the big puzzle. (So I am not complaining about too few documentation in
general.)
However the way how this documentation is presented to the user could get
improved imho. Specifically I miss some real "walkthrough" that takes the
absolute beginner and covers all topics (from a user's perspective with typical
use cases) in a sensible order from the easy to the complex. Something like a
guide that answers among others the questions:
- "What do I need to know first. Wich topics to learn in which order."
- "Where find I more backgournd details about ...",
- "What is the current state of GeoTools: What is it capable of, what not?")
I've read a lot of good "all in one" tutorials/manuals of this sort, such as
- "Version Control with Subversion" or the
- "PostgreSQL 8.0.0 manual" (postgresql-8.0-A4), or
- IDL tutorial/user's guides (They use linked PDFs and are excellent imho.)
The uDig beginner's tutorial is also good in this respect, although it only
covers the really simple things.
The main point is, that the GeoTools learning curve is imho quite steep for the
typical GIS user (not computer scientist), and this is even more pronounced by
the fact that the API is changing fast. Sometimes I have the impression that as
soon as I understand something it is about to change to something more complex
in the next version. (In ecology this is called the "Red Queen hypothesis" -
one has to run to stay on the same spot).
It should imho be the task of a good documentation to shield the average user
from this impression and the ongoing RnD work and to give him/her the feeling
of working on a stable API.
I'd like to help with documentation, but as long as I havn't understood most
APIs myself I doubt this makes much sense.
4. Spin-off ... and back in
---------------------------
It became obvious that there is often the need (and will be always) for some
stakeholders to create some functionality quickly (often under pressure of a
deadline). They can often not wait for the complete release cycle including the
steps discussed in point 1. uDig - it seems - has tought us some lessons.
My idea is that there should - for each project working on top of Geotools - be
three "workspaces" (any better word appreciated):
- GeoTools workspace
- GeoTools-aimed quick and dirty workspace
- Application workspace
The "GeoTools workspace" holds what is where in GeoTools or what can be quickly
incorporated or can be incorporated in the usual GeoTools release cycle.
The "Quick and dirty workspace" is for work that is aimed to be incorporated
into GeoTools later, but (since under time pressure) cannot run through the
offical GeoTools release cycle but is needed to run, f.e., earlier than the
next release. It would be part of the application until it becomes incorporated
into the GeoTools workspace (after approval).
The point is that this workspace would follow certain GeoTools developer rules:
- no dependencies on application specific libraries or modules (i.e.
independence from the "Application workspace").
- follow GeoTools coding guidelines as far as possible This ensures that
incorporation into GeoTools will later work with as few problems as possible.
Both GeoTools and application developers should have access to this workspace.
The "Application workspace" would hold any code that is not supposed to become
part of GeoTools later.
5. Facades, two-level API
-------------------------
I believe that GeoTools could become a much more user-friendly API if it had a
strict two-level API and developer guidelines that facilitate it.
- A high-level API with functions as the usual GIS USER(!) would expect them.
- Typical GIS terminology for functions
- Task-based, liberal API (just have the really necessary functions and
methods in the interfaces, implementations have the freedom to perform
the tasks as they like.)
- No use of "Blackboards", "visitors" or any advanced Java techniques
(Users should not need to read the GOF's book to understand it).
- Hiding of different implemetations (remote vs. local, DB vs. file,
different specification versions etc. )
- Hiding of "complex" things, even if this covers only
95% of the functionality
- Hiding of performance tweaks
- STABLE over several versions of GeoTools
- Well-documented extension/entry points, f.e. to do scientific stuff
with the data, add a new file format, ... (It is my impression that this
works quite well in uDig already.)
- A lower-level API with functions as the COMPUTER EXPERT would require them
- access complete functionality, including "complex" extensions
- possibility to change implementation at a quicker rate, incorporate tweaks
- everything allowed...
- interfaces more closely mirroring the OGC (or other) specifications.
Not all parts of GeoTools need such two level API. I consider it very important
for
- Styling API. The GeoAPI interfaces are NOT what a GIS user would expect.
- Features/attributes (Most GIS users see the classical shapefile attribute
table before their eyes when they hear "attributes", and a high level API
should imho try to reflect this.)
- Data I/O (There is a high level API there as a good starting point.)
- Geometry/Topology API? Not sure.
I consider it not necessary for
- MapFramework API (There isn't anything complex to hide yet.)
- Referencing API (This is already intuitive in my opinion.)
- Rendering (This is not something a GIS user would usually care about.
It is expected to "simply work".)
OK. These are just mine ideas.
Matthias Basler
[EMAIL PROTECTED]
----------------------------------------------------------------
This mail was sent through http://webmail.uni-jena.de
-------------------------------------------------------
SF.Net email is sponsored by:
Tame your development challenges with Apache's Geronimo App Server.
Download it for free - -and be entered to win a 42" plasma tv or your very
own Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php
_______________________________________________
Geotools-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/geotools-devel
