[OpenLayers-Dev] Additional Documentation

Christopher Schmidt crschmidt at metacarta.com
Thu Nov 13 07:02:56 EST 2008

I've been maintaining
http://crschmidt.net/~crschmidt/spherical_mercator.html for the past 11
months in my own personal SVN server.

I would like to stp doing that, and put it instead in OpenLayers SVN. It
seems t me that we cuold be writing a number of documents like this --
single page sheets about a particular feature of OpenLayers. My hope is
that if we were to have a central location for these things:

1. People would be more able to find them.
2. We woul dhave a centralized place to host translations/other related
3. We could integrate deployment of these materials onto openlayers.org
   somewhere more easily.

I understand that some people will continue to maintain their own
seperate repositories for documents as well, adn I'm not arguing against
that, of course.

What I would like to do is: 

 * Create http://svn.openlayers.org/trunk/doc/
 * Check in the build directory from the SVN above
 * Create a "spherical_mercator" subdirectory
 * Check in the spherical_mercator.rst file
 * Add a 'build' script that will iterate over directories, looking for
   potential RST to build.

The only reason to put the build tools above is that I believe this

Then, as we build up more documentation, we have a framework for more
prose documentatin like this: simply create a subdirectory for it, and
any neccesary information can be stored alongside it.

I believe that translations of documents could also be managed this way: 
simply have a spherical_mercator.fr.rst document alongside the English
one, for example.

At this time, I'm not proposing commit status for this directory be
given to people who don't already have trunk commit, but we can imagine
making this sectino more 'open' to other committers (possibly even all
of our sandbox users), since commits are less likely to 'break' things. 

I guess this type of thing really should be a PSC vote, so:

Does anyone have any objections to creating trunk/doc/, putting some
useful build utils in it, as well as creating subdirectories for
individual prose documentation efforts, starting with the
spherical_mercator.rst describe above? 

I'll start off by saying I'm +1.

Christopher Schmidt

More information about the Dev mailing list