[Geoserver-devel] New documentation framework - Update!

[Mike P. <mi...@op...>]

Greetings all.  As you may or may not recall, GeoServer is revamping its documentation! [1]

A few of us have been working to come up with the basic framework for the new user guide (with the developers guide in progress as well).  The new documentation is being rendered using Sphinx [2], and written in reStructuredText [3].

The major benefits of this move, as discussed and approved in late 2008, are:
   Documentation in version control
      - Version specific documentation
   New output formats
      - Better output for HTML
      - PDF (coming soon)

Anyway, the docs are coming along, however, I'd like to leverage the benefits of the community that we have here.  So I'm proposing that we start to move our documentation efforts to the new site.  (This is currently in source code at [4], and built to view at [5], although it will be moved.)  There is much work that needs to be done on the new docs, but we've made a good start. 

Issues that come to mind are:

1) Setting up a permanent repository for versioned docs.
    We discussed in the IRC meeting today [6] to have the docs possibly hosted at http://docs.geoserver.org/x.y.z

2) Deprecating the current docs
    Confluence won't be going away, but the current docs (hosted in the GEOSDOC space) should possibly have a notice posted saying that they are not the current version of the docs.  I was thinking a global banner over the top, but we can hammer out details.  Also, I hope the wiki will morph into a "community" docs section, where anyone can still contribute, but the work will need to be peer reviewed before it becomes part of the official documentation.

This email is to get the discussion started.  What questions/comments/reservations do you have?


[1] http://geoserver.org/display/GEOS/GSIP+25+-+New+Documentation+Framework
[2] http://sphinx.pocoo.org/
[3] http://en.wikipedia.org/wiki/ReStructuredText
[4] https://svn.codehaus.org/geoserver/branches/1.7.x/doc/user/
[5] http://gridlock.openplans.org/geoserver/1.7.x/doc/user
[6] http://geoserver.org/display/GEOS/2009/03/31/IRC+Logs%2C+March+31%2C+2009


Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org