[Geoserver-devel] New documentation framework - Update!

GeoServer GeoServer Developer
1

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

2

Thanks for the update.

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

A question; is this a url to the published documentation (ie an
alternative to http://gridlock.openplans.org/geoserver/1.7.x/doc/user)
or is it an svn repository for working on the docs?

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.

I am just watching the eclipse community migrate in the other
direction; their official docs now point to the appropriate wiki page
for the latest version. However I really like the idea of keeping our
docs from release to release.

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

Sounds good; We may want to change the examples in the writing
guidelines from confluence to ReStructuredText.

Jody

3

Hi Jody.

A question; is this a url to the published documentation (ie an
alternative to http://gridlock.openplans.org/geoserver/1.7.x/doc/user)
or is it an svn repository for working on the docs?

I think docs.geoserver.org would probably be a link to the built docs (i.e. gridlock). The source docs would continue to be accessed via svn in the same way that code is.

However I really like the idea of keeping our
docs from release to release.

The example I used during the meeting today was the KML reflector, whose syntax changed in version 1.7.1. If I were running 1.6.5, and I only had links to the latest docs, I would find incorrect syntax. This also alleviates the need for tiresome lists like "if you are running _this_ version, do _that_".

Sounds good; We may want to change the examples in the writing
guidelines from confluence to ReStructuredText.

This is definitely needed, and a documentation meta-guide was started here (no built version exists yet):

https://svn.codehaus.org/geoserver/branches/1.7.x/doc/guide/source/

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

Jody Garnett wrote:

Thanks for the update.

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

A question; is this a url to the published documentation (ie an
alternative to http://gridlock.openplans.org/geoserver/1.7.x/doc/user)
or is it an svn repository for working on the docs?

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.

I am just watching the eclipse community migrate in the other
direction; their official docs now point to the appropriate wiki page
for the latest version. However I really like the idea of keeping our
docs from release to release.

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

Sounds good; We may want to change the examples in the writing
guidelines from confluence to ReStructuredText.

Jody

4

Oh, one more thing. Since the Sphinx docs are incomplete, and we don't want to port every single doc onto the new system, there are likely to be docs in Confluence that slip through the cracks. If you find some content that's not referenced in the Sphinx docs, please file JIRA tasks for them. Since the documentation is now in version control, it makes sense to think of missing documentation as bugs to be fixed.

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

Mike Pumphrey wrote:

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

------------------------------------------------------------------------------
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel