Added by jgarnett, last edited by jgarnett on Sep 17, 2008  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Guidelines for writing in the GeoTools User Guide

GeoTools User Guide Contents:

Welcome

The Welcome section of the Users Guide is devoted to introduction material and tutorials.

Since there is no module maintainer for overview and background knowledge of this nature we need to be very careful that it is always up to date.

  • All example code used in the wiki must be present in the demo folder.

By making use of the demo folder we will ensure that the code:

  • Compiles and Functions
  • Is kept up todate as API changes occur

It is the responsibility of those making an API change to update the demo code, and associated wiki pages. Please be kind and include a link to the wiki page in your demo code javadocs.

Welcome Contents:

Welcome Writing Guidelines

When writing for the welcome section please consider the target audience as experienced in Java, but not experienced with spatial constructs and ideas. We must focus on results, not correctness.

Here are some examples:

  • Introduce the concept of a Feature, but not Java Generics
  • Show first, explain after - given your target audience showing them the source code first will put them at ease. That way when you are talking about what a Feature means afterwords they will know to pay attention (it is after all a real concept that they must deal with in the form of a Java interface).
  • Leave the specifications out of it as much as possible. You can link to the specifications as "related information", and talk about ideas such as ISO Geometry - but do not drive people crazy. They are here to get a job done - it is your job to understand the specification so they do not have to.

You can create a "Welcome for..." page if you have a different target audience in mind.

Reference Material

The bulk of our user guide is devoted to reference material, on a module by module basis. Please keep in mind that this is reference material focused on results - ie code examples to accomplish a specific purpose. We do not need a bunch of design documentation here, show us what your code can do.

You may want to briefly introduce any new concepts specific to your module, but please leave the definitions of what things are to the javadocs.

As an example:

  • When documenting Main you can mention what a Feature is used for - since DefaultFeature is the first implementation a user will have used.
  • When documenting WFS you can mention what a Web Feature Server is - since that is the new concept for your plugin, but please don't define what a Feature again.
  • Focus on useful results and examples, leave the background information to the specifications and welcome section

Do not:

  • You do not need to go all out and define the interfaces - we have javadocs for that.

General Approach

The GeoTools user guide is set up as a one two punch:

  • One: The Javadocs define the Concepts (users can see what a class is when they look at a tooltip in their IDE)
  • Two: The Reference Material here provides example code

The expected Use of this material is (honestly):

  1. User finds the wiki page using google
  2. They cut and paste the source code into their program
    (They may curse a bit as they hunt down dependencies but that is not your fault)
  3. Their IDE can show them the Javadocs for any classes (incase they wonder what something is).

With this in mind our goal is to provide code examples showing how to perform common tasks.

Documenting a Module

Each page of documentation is prefixed with a number; in order to ensure order when exporting the user guide. If possible try and use a {toc} (table of contents) tag near the top to allow users to quickly navigate down the page.

A FeatureCollection is used to represent a set of Features (often returned as the result of a query):
{toc}

Related:
* [02 FeatureSource]

h1. Creating a FeatureCollection

h2. Using FeatureSource.getFeatures()

h2. Using FeatureCollections.newInstance()

h1. Using a FeatureCollection

h2. FeatureVisitor

h2. Iterator

h2. Feature Iterator

It looks like using a number to prefix the page name may not be strictly required anymore (since a new update to Confluence lets us set page order)

Code Examples

Please isolate complete working examples as a demo module. For most quick examples taking content from your tests cases will be just fine. Please remember to mention the wiki page in your javadocs, so we can keep the two in sync.

If you are really lazy you can provide link to your test case in from the wiki - so users can check that the example code is still valid themselves.

Documenting Plug-ins for a Module

Each module that allows plug-ins should have the plug-ins listed as child pages; there is no need to "prefix" these pages with a number as Alphabetical order will be fine (every plugin is considered equal).

Extensions

The extensions are functionality that are built "on top" of the core library; we have a child page for each extensions.

Extensions Contents:

Unsupported

Unsupported modules (that bother to have any documentation at all) are listed here - one child page for each unsupported module. This is mostly used as a staging area when an unsupported module is getting ready and meeting its documentation requirements.

Unsupported Contents:

Advanced

Advanced Materials cover "Intergration" of GeoTools with facilities provided by an existing application.

  • Easy: Logging (teaching GeoTools how to make use of an application's existing logging facilities)
  • Medium: Making use of a Java EE application server that shares JDBC Connection Pools between running applications
  • Hard: An organizations that has a single EPSG database for a workgroup (and have registered this database as a JNDI service).

All of these issues boil down to careful application of:

  • Factories (how you can teach uDig new tricks)
  • Hints (generally used to inject your own Factory into GeoTools)

Advanced Contents:

Guides

Advanced Guides on specific topics; the target audience is now a fellow GeoTools developer who wishes to implement a new plugin.

Guides Contents:

Depreacted

A collection of old reference material that is now outdated; copy old code examples here as API is updated.