Currently I am exporting out the docs from a word munching program; this allows
me to easily change the structure quickly.
Can I ask people to review the current structure of the docs; and ask for any
changes they need now; then I can open up the doc module to more general
contribution and fixing.
IF YOU HAVE ALREADY CONTRIBUTED
I have been trying to check if others are writing into the doc; but there is a
chance I will just overwrite your work at the moment; please email me with doc
changes.
Can you take a moment to check for your writing to see if we need to recover it
from svn?
FOR CONTRIBUTING TO THE DOC
I do have a couple of ground rules for the docs.
1. do not use cross references
NO: .. _feature_tutorial: followed by :ref:`feature_tutorial`
YES: :doc:`/tutorials/quickstart.eclipse`
2. Use doc references
:doc:`gt-main </library/main/index>`
:doc:`gt-main feature implementation </library/main/feature>`
3. Reference images and source code relative to the root of the document (this
allows text to be moved around quickly without fear of breaking links).
.. image:: /images/SimpleFeatureSource.PNG
.. literalinclude::
/../src/main/java/org/geotools/data/SimpleFeatureStoreExamples.java
:language: java
:start-after: // removeExample start
:end-before: // removeExample end
4. Finally you may (or may not be surprised) that all the code examples are not
live.
For each module I have tried to have one XXXExample.java file; with an example
of how "literalinclude" works. The idea being that the code
examples can gradually become real as you have a chance to work on them.
5. Structure
http://docs.geotools.org/latest/userguide/library/jdbc/index.html
Each section has an "index.txt" page that includes the others
There is an svg picture showing where people are; the svg is in version control
if you need to update it.
http://docs.geotools.org/latest/userguide/library/jdbc/internal.html
Each section has an "internal.txt" or a complete folder "internal/index.txt"
that contains all the design details and other
stuff that is not directly concerned with *use*
http://docs.geotools.org/latest/userguide/library/jdbc/faq.html
Each section has a "faq.txt" which is included in the root "faq.txt" allowing
users to have a "question based lookup".
http://docs.geotools.org/latest/userguide/extension/validation.html
http://docs.geotools.org/latest/userguide/library/opengis/model.html
Each page can have a "References" list linking to related stuff; please try
and do this after the initial intro paragraph to avoid
sprinkling links all over the place in your text and getting off topic.
And yes I need to write this into the developers guide (to replace the existing
wiki writing guidelines)
--
Jody Garnett
------------------------------------------------------------------------------
Benefiting from Server Virtualization: Beyond Initial Workload
Consolidation -- Increasing the use of server virtualization is a top
priority.Virtualization can reduce costs, simplify management, and improve
application availability and disaster protection. Learn more about boosting
the value of server virtualization. http://p.sf.net/sfu/vmware-sfdev2dev
_______________________________________________
Geotools-devel mailing list
Geotools-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geotools-devel
