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:

1. The Javadocs define the Concepts (users can see what a class is when they look at a tooltip in their IDE)

2. 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 if the example code is still valid.

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.

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.

Advanced
^^^^^^^^

Advanced Materials cover "Integration" 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 organisation 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)

Guides
^^^^^^^

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

Deprecated
^^^^^^^^^^

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