Message-ID: <1321216319.13151.1416802341831.JavaMail.firstname.lastname@example.org> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_13150_283223953.1416802341831" ------=_Part_13150_283223953.1416802341831 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
This page documents steps taken to improve our GeoTools document= ation for users (aka those programmers who use geotools as= a library). This page was started in April 2006 around the 2.2.RC2 version= of Geotools.=20
The following work has been started:=20
The proposal is presented at the top. Below is the stream of discussion = during development of the proposal.=20
A "Programmer's Manual" will be created, similar to the = "Developer's Manual," but focused on users of the Geotools librar= y rather than those improving the library itself.=20
The idea of this documentation project is to make a minimum amount of wo= rk for maintenance while giving users a solid start into the codebase. = ;=20
This proposal does demand of the pr= oject that it make a commitment to keeping the tutorials in functioning ord= er by updating the tutorials when the Geotools library changes.= =20
Okay so this page gathers together some ideas towards fixing the docs, i= t will not cover why they are broken. This is part of the geotools "gr= owing up" process, and something we want to nail before graduation fro= m the OSGEO inccubation process.=20
I would just like to thank the community for the strong show of support = for this topic, we all know it is important, and this page outlines what is= going to be done.=20
I also must appologize for my focus here, I am not look= ing for more, I am looking for less. The goal here is to = identify what documentation we can maintain and keep up to date as a commun= ity, we can add additional things later.=20
Yes our toys are fun, once they use it they will know.=20
They will see us on the email list, the wiki signs our work, svn blame k= nows all and we thank our sponsors on seperate page.=20
The user cannot be asked to keep TC211, 19119, 19115 and so on straight,= just don't go there girl friend!=20
Tip: use the language as if the user knew what you were talking about. S= ay Feature and Geometry and Metadata.=20
Any thing covered by a specification or a book, we are not an intro. (I = feel bad about this but we need to get our own house in order before we can= try and help people learn GIS, I know you are all excited about the field,= and many of you teach, but this has got to be a firm requirement).=20
We are here to document a library, not explain what is going on. Documen=
t as if the reader
Patterns are fun, tradeoffs are fun. Users do not care. I will need to r= estrain my self.=20
We are not here to explain why transacction is such a cool use of patter= ns, or why the graph api is so good. It is obvious that WMS uses the strata= gy pattern when you read the class names, the reader can understand from WM= S1_1_0Stratagy class what forces were balanced (and why),=20
No time spent on justification, much like the decision to leave ISO 1911= 9 naming this is better handled in javadocs. We are focused on use, not def= ence. This is code, if it runs who cares.=20
No Omondo, No Viso nothing we cannot keep up to date. I know it is next = to impossible to explain the big picture without a picture. Talk to Andrea = about getting diagrams as part of our javadocs.=20
I am not intereted in explaining the big picture right now, we can write= some articles later. The small picture will do as long as we explain enoug= h small pictures. We can organize our docs bottom up however so that by the= time we are looking at rendering the SLD will not scare them.=20
So after all that what is left? Here is a set of guidelines that have pr= oduced usable docs, and have been explicit enought to make writing easy.=20
Yes it looks like we could write a tutorial here, and you can (just not = now).=20 =20
Just the facts, these serve to keep us for explaining what a Feature is =
badly on many different pages. This gives us
a single page to explain= what a Feature is badly This is also where we would link to external = resources like OGC
and ISO specifications.
2.3: No specific goals, just write a page here when you are tempted to e=
2.next: it would be nice to walk through each specif= ication and make sure we have it covered.
Numbered list indicating how a given task should be performed in prose.<= /p>=20=20
Include a code example at the end. The
code example must be upto d= ate, even if all it ends up being is a link to a file in the demo directory= . If we can
inline the code example from svn we will do it.
This is mostly covered by javadocs - go team! This is where many of the =
articles will go to die, anything
worthwhile should be placed in the = codebase in doc-files directories.
I am tagging in Adrian here as a champion of the user, his dedication to= larning geotools has been great. And I hope that all his scars have not ye= t healed, so he can help us remember what there is to trip over.=20
Now we did spend some time offline on scope, and we are finding some com= mon ground.=20
If we are going to do this well, we must ensure that we have a minimum coverage of all the basic topics: Data Model, Rendering Model, ( not Control since that's implementation dependent).=20
Snippets are fine later in the process but are not good intros because they don't give the import statements (which are critical to finding t=
I think we should expect to have a working human readable example+test for each of the datastores.=20
Cover the entire library
Have code examples (that run) rather = then snippets
I am scared of code example for each datastore, I = would rather have developers use the API
Much like for uDig, I think you all should put together a full,
he= avy-weight SDK package which includes all the binary, source and
docu= mentation data. The idea is to show people how to read the code and
j= avadocs as much as how to code because we are trying to ge= t them to
become self-sufficient as quickly as possible. This means t= hat the JTS
jar, for example, must include source and ideally the ecl= ipse metadata
so we can skip into that code when we hit it. I would d= o this myself but
I have no clue how to do this. Act= ually, I would be interested to
As a corrollary, I would like our examples to end with 'further code
reading' pointing to sections of the code that do similar things. This would help introduce people to the geotools packages as well.
Getting Started: Starting a Maven 2 Project
Getting Started: S= tarting a Eclipse Project (using a binary and source download)
We can start this now (since referencing is stable for 2.3.x). We can us=
this as an example for review during Monday's meeting.
Transformation is at the core of the geo aspect of the library. I
= suspect we need to start with an explanation of CRS at least so far as
mentioning the different kinds of CRS's and the EPSG authority.
This page is great:
http://svn.geotools.org/geotools/= trunk/gt/demo/referencing/src/org/geotools/demo/referencing/CTSTutorial.jav= a
but not so much as a snippet.
This would result in a simple projection converter:
geoProjectionC= onvert --input simple.shp --output WGS84 reproject.shp
again working as an example.=20
We will not have introduced Shapefiles yet, so the converter is not= going to work as an example=20
We still got to work through this one, Jody wanted this:
Introdu= ce FeatureType (aka the Feature Model)
Introduce Feature (aka the D= ata model)
Introduce Expression (data acess)
Introduce Filt= er (query language)
Introduce Data Reading
Introduce Data W= riting
And Adrian wants to go the other way:=20
Building a Feature was critical for me since that was an intro to the
Data Model. Actually, I would like a three part:
Each of these would be a seperate application, we had thought of a simpl=
file converter bringing them together (but it made Jody nervous).= p>=20
on complete examples programs, if possible I would like to use the sim=
to allow the examples to remain independent of shapefi= le for as long as possible.
This should obviously wait until they have refactored the renderer. If we need to write the MapPane then let's do it---you have seen how
painful the current situation is to new users. (let's delete the others)<= br /> and leave links on the wiki to revisions where they can be found.
Removing the others (they are already "gone" due to legacy d= ependency)=20
Similarly, I would like a=20
Greate we can use this to make earlier examples visible,
and the= n explain how it was done here.
These can be more freeform, more compact (snippets) more vague. By the time a user gets to these, she has a solid background in navigating an=
using the library so we can be more terse.
Lets just not do this, remember the 80% focus