Developer Documentation Writing Guidelines

Developer Documentation is where we get a chance to help volunteers help themselves (and us). Writing Developer Documentation is a tricky balance between describing what GeoServer does, how it works, and why it was constructed that way. Chances are that much of the technology will either be brand new to developers this year, and old hat next year.

Restrictions

Describe what GeoServer does - right now
Do not explain why (it get in the way)
Do not explain what GeoServer does

Goals

Initial Goal
1. Aquire source code and builder
2. Run in debugger to fix a bug
Secondary Goals
3. Extend geoserver
4, Correct Documentation
Advanced Goals
5. Use module system in custom app
6. Reuse geoserver modules in custom app |

Target Developer

Here is a great working assumption when writing GeoServer documentation

Java Developer
uses Eclipse
Some J2EE Experience, has made a Servlet and has looked at JSP code
No subversion experience, so command line example needed when subversion is used
No maven experience, so command line example needed when subversion is used
No Struts experience
No Swing experience

We are here to explain GeoServer, so links to external documentation are fine, we are not the best people to explain Struts after all.

Quickstart Guidelines

Target Developer Goals:

start geoserver up in a debugger to fix a problem

Guidelines:

Keep it straight and to the point, a sentence with a step by step procedure
We are here to acomplish a specific task

Programmers Guide

Target Developer Goals:

Extend GeoServer

Guidelines:

We are to provide context beyond source code
Guide read in order, can assume they read the previous section
Document what is

An additional restriction is in place during the change over to the module system, please restrict the Programmers Guide to only document modules "approved" by Justin. Code that he wants replaced, like the STRUTS config application,

Reference

Target Developer Goals:

Look up specifics

Guidelines:

link to generated docs (javadocs etc...)
document where GeoServer can be extended
"Other" captures articles providing in-depth knolwedge and background information

If you cannot resist pontificating about WFS-T, or how Rendering really works, then write an artice and place it under "Other".

FAQ and Index

Goals:

cut down on email
send out link rather then answering common email questions

Use parent/child relationships to keep FAQ straight, where possible link directly to section in programmers guide.